From 6ab4da1ddee4d5b074f9e50b4f7118e1fdb1e829 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Tue, 5 Sep 2023 01:12:46 -0700 Subject: [PATCH] feat: SchemaRecord, never write a Model again --- .eslintignore | 1 + .gitignore | 1 + packages/json-api/package.json | 2 +- packages/schema-record/.npmignore | 40 ++++ packages/schema-record/LICENSE.md | 11 + packages/schema-record/README.md | 191 ++++++++++++++++++ packages/schema-record/addon-main.js | 93 +++++++++ packages/schema-record/babel.config.js | 13 ++ .../schema-record/ember-data-logo-dark.svg | 12 ++ .../schema-record/ember-data-logo-light.svg | 12 ++ packages/schema-record/package.json | 93 +++++++++ packages/schema-record/rollup.config.mjs | 31 +++ packages/schema-record/src/index.ts | 6 + pnpm-lock.yaml | 86 ++++++++ tsconfig.root.json | 3 + 15 files changed, 594 insertions(+), 1 deletion(-) create mode 100644 packages/schema-record/.npmignore create mode 100644 packages/schema-record/LICENSE.md create mode 100644 packages/schema-record/README.md create mode 100644 packages/schema-record/addon-main.js create mode 100644 packages/schema-record/babel.config.js create mode 100644 packages/schema-record/ember-data-logo-dark.svg create mode 100644 packages/schema-record/ember-data-logo-light.svg create mode 100644 packages/schema-record/package.json create mode 100644 packages/schema-record/rollup.config.mjs create mode 100644 packages/schema-record/src/index.ts diff --git a/.eslintignore b/.eslintignore index 84ee7490e50..2635ad3c0be 100644 --- a/.eslintignore +++ b/.eslintignore @@ -22,6 +22,7 @@ /packages/rest/addon/ /packages/active-record/addon/ /packages/data-worker/addon/ +/packages/schema-record/addon/ **/DEBUG/ diff --git a/.gitignore b/.gitignore index 35d81b922f8..49eacd365cd 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ packages/request-utils/addon packages/rest/addon packages/active-record/addon packages/data-worker/addon +packages/schema-record/addon/ # dependencies bower_components diff --git a/packages/json-api/package.json b/packages/json-api/package.json index eab487b7cef..8976b8d7cf8 100644 --- a/packages/json-api/package.json +++ b/packages/json-api/package.json @@ -8,7 +8,7 @@ "repository": { "type": "git", "url": "git+ssh://git@github.com:emberjs/data.git", - "directory": "packages/record-data" + "directory": "packages/json-api" }, "license": "MIT", "author": "", diff --git a/packages/schema-record/.npmignore b/packages/schema-record/.npmignore new file mode 100644 index 00000000000..e4bce62a5ec --- /dev/null +++ b/packages/schema-record/.npmignore @@ -0,0 +1,40 @@ +# compiled output +/dist/ +/dist/**/* +/tmp/ +/types/ +**/*.d.ts + +# dependencies +/bower_components/ + +# misc +/.bowerrc +/.editorconfig +/.ember-cli +/.env* +/.eslintignore +/.eslintrc.js +/.gitignore +/.template-lintrc.js +/.travis.yml +/.watchmanconfig +/bower.json +/config/ember-try.js +/CONTRIBUTING.md +/ember-cli-build.js +/testem.js +/tests/ +/yarn.lock +.gitkeep + +# ember-try +/.node_modules.ember-try/ +/bower.json.ember-try +/package.json.ember-try + +# ember-data +/node-tests + +# whitelist yuidoc's data.json for api docs generation +!/dist/docs/data.json \ No newline at end of file diff --git a/packages/schema-record/LICENSE.md b/packages/schema-record/LICENSE.md new file mode 100644 index 00000000000..97a483b5d8f --- /dev/null +++ b/packages/schema-record/LICENSE.md @@ -0,0 +1,11 @@ +The MIT License (MIT) + +Copyright (C) 2017-2023 Ember.js contributors +Portions Copyright (C) 2011-2017 Tilde, Inc. and contributors. +Portions Copyright (C) 2011 LivingSocial Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/packages/schema-record/README.md b/packages/schema-record/README.md new file mode 100644 index 00000000000..0a0ae7f3b7e --- /dev/null +++ b/packages/schema-record/README.md @@ -0,0 +1,191 @@ +

+ + +

+ +

🌲 Get back to Nature 🐿️ Or shipping 💚

+ +SchemaRecord is: +- ⚡️ Fast +- 📦 Tiny +- ✨ Optimized +- 🚀 Scalable +- :electron: Universal + +Never write a Model again. + +This package provides presentation capabilities for your resource data. It works together with an [*Ember***Data**](https://github.com/emberjs/data/) [Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) and associated Schemas to simplify the most complex parts of your state management. + +## Installation + +Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/) + +```no-highlight +pnpm add @ember-data/schema-record +``` + +## Getting Started + +If this package is how you are first learning about EmberData, we recommend starting with learning about the [Store](https://github.com/emberjs/data/blob/main/packages/store/README.md) and [Requests](https://github.com/emberjs/data/blob/main/packages/request/README.md) + +## 🚀 Setup + +SchemaRecord integrates with EmberData via the Store's resource lifecycle hooks. +When EmberData needs to create a new presentation class to pair with some resource +data, it calls `instantiateRecord`. When it no longer needs that class, it will call +`teardownRecord`. + +```ts +import Store from '@ember-data/store'; +import SchemaRecord from '@ember-data/schema-record'; +import Cache from '@ember-data/json-api'; + +const DestroyHook = Symbol.for('destroy'); + +export default class extends Store { + instantiateRecord(identifier) { + return new SchemaRecord(this, identifier); + } + + teardownRecord(record: SchemaRecord): void { + record[DestroyHook](); + } +} +``` + +## Start Using + +Any Store method that returns records will use SchemaRecord once configured as above. +After that, its up to you what SchemaRecord can do. + +SchemaRecord's behavior is driven by the Schemas you register with the Store's Schema +Service. Schemas are simple json objects that follow a pattern. + +You could manually construct schemas, though that would be laborious. We recommend +compiling schemas from another available source such as your API's types. If you don't +have a source from which to compile schemas, consider using `@ember-data/schema-dsl`. + +The Schema DSL allows authoring rich, expressive schemas using familiar Typescript and +Decorators, which compile at build into json schemas you can deliver to your app either +in your asset bundle, via a separate fetch, or from your API. + +The Schema DSL will also compile and register types for your schemas that give you robust +typescript support. + +## Main Paradigms + +### Immutability + +SchemaRecord is Immutable. This means by design you cannot mutate a SchemaRecord instance. + +How then do you make edits and preserve changes? + +### Mutation Workflows + +Edits are performed in mutation workflows. A workflow is begun by forking the store. +Forks are cheap copy-on-write scopes that allow you to make changes in isolation without +affecting the global state of the application (until you want to). You can even fork forks, though its probably not that useful to do so in the common case. + +```ts +const fork = await store.fork(); +``` + +Forks are not themselves editable, they are just a pre-requisite. +There are three ways to get an editable SchemaRecord instance. + +1. Create a new record with `const editable = fork.createRecord(, data)` +2. Checkout an existing record in edit mode: `const editable = fork.checkoutRecord(record)` +3. Access a related record on a record already in edit mode: `const editableFriend = editable.bestFriend` + +If you decide you want to discard your changes, there's no need to rollback. Simply +dereferencing the fork and any records you've received from it will cause it to GC. + +However, explicitly calling `fork.deref()` will ensure that if you did forget to dereference +any records and left them around somewhere as a variable, they'll blow up with a useful +error if used again. + +To save changes, call `fork.request(saveRecord(editable))`. Saving changes will only commit +the changes to the fork, it won't commit them upstream. To reflect the changes upstream, call +`await fork.merge(store)`. In most cases, `store` should be the store you forked from, though +it is allowed to attempt to merge into a parent `store` as well. + +```ts +// get a fork for editing +const fork = await store.fork(); + +// create a new record +const user = fork.createRecord('user', { name: 'Chris' }); + +// save the record +await fork.request(createRecord(user)); + +// reflect the changes back to the original store +await store.merge(fork); +``` + +> Note: merging behavior is determined by the Cache implementation. The implementations +> maintained by the EmberData team will merge both persisted and unpersisted changes back +> to the upstream (preserving them as remote and local state respectively). This approach +> allows developers to choose to optimistically vs pessimistically update the global state. + +### Optimistic UX + +```ts +// get a fork for editing +const fork = await store.fork(); + +// create a new record +const user = fork.createRecord('user', { name: 'Chris' }); + +// reflect the (dirty) changes back to the original store +await store.merge(fork); + +// save the record +await fork.request(createRecord(user)); + +// reflect the (clean) changes back to the original store +await store.merge(fork); +``` + +## Schema Format + +The schema format is the array representation of a Map structure. From which +we will populate or append to a Map! + +```ts +[ + [ 'user', ], + [ 'company', ], +] +``` + +It follows this signature: + +```ts +type ResourceType = string; // 'user' +type FieldName = string; // 'name' +type FieldDef = { + name: string; + type: string | null; + kind: 'resource' | 'collection' | 'attribute' | 'derivation' | 'object' | 'array'; + options: Record; +}; + +type ResourceSchema = Array<[FieldName, FieldDef]> +type Schemas = Array<[ResourceType, ResourceSchema]> +``` + +You'll find this syntax is capable of describing most conceivable behaviors, including +some emergent ones we're sure we haven't thought of yet. diff --git a/packages/schema-record/addon-main.js b/packages/schema-record/addon-main.js new file mode 100644 index 00000000000..1dbde47c342 --- /dev/null +++ b/packages/schema-record/addon-main.js @@ -0,0 +1,93 @@ +const requireModule = require('@ember-data/private-build-infra/src/utilities/require-module'); +const getEnv = require('@ember-data/private-build-infra/src/utilities/get-env'); +const detectModule = require('@ember-data/private-build-infra/src/utilities/detect-module'); + +const pkg = require('./package.json'); + +module.exports = { + name: pkg.name, + + options: { + '@embroider/macros': { + setOwnConfig: {}, + }, + }, + + _emberDataConfig: null, + configureEmberData() { + if (this._emberDataConfig) { + return this._emberDataConfig; + } + const app = this._findHost(); + const isProd = /production/.test(process.env.EMBER_ENV); + const hostOptions = app.options?.emberData || {}; + const debugOptions = Object.assign( + { + LOG_PAYLOADS: false, + LOG_OPERATIONS: false, + LOG_MUTATIONS: false, + LOG_NOTIFICATIONS: false, + LOG_REQUESTS: false, + LOG_REQUEST_STATUS: false, + LOG_IDENTIFIERS: false, + LOG_GRAPH: false, + LOG_INSTANCE_CACHE: false, + }, + hostOptions.debug || {} + ); + + const HAS_DEBUG_PACKAGE = detectModule(require, '@ember-data/debug', __dirname, pkg); + const HAS_META_PACKAGE = detectModule(require, 'ember-data', __dirname, pkg); + + const includeDataAdapterInProduction = + typeof hostOptions.includeDataAdapterInProduction === 'boolean' + ? hostOptions.includeDataAdapterInProduction + : HAS_META_PACKAGE; + + const includeDataAdapter = HAS_DEBUG_PACKAGE ? (isProd ? includeDataAdapterInProduction : true) : false; + const DEPRECATIONS = require('@ember-data/private-build-infra/src/deprecations')(hostOptions.compatWith || null); + const FEATURES = require('@ember-data/private-build-infra/src/features')(isProd); + + const ALL_PACKAGES = requireModule('@ember-data/private-build-infra/virtual-packages/packages.js'); + const MACRO_PACKAGE_FLAGS = Object.assign({}, ALL_PACKAGES.default); + delete MACRO_PACKAGE_FLAGS['HAS_DEBUG_PACKAGE']; + + Object.keys(MACRO_PACKAGE_FLAGS).forEach((key) => { + MACRO_PACKAGE_FLAGS[key] = detectModule(require, MACRO_PACKAGE_FLAGS[key], __dirname, pkg); + }); + + // copy configs forward + const ownConfig = this.options['@embroider/macros'].setOwnConfig; + ownConfig.compatWith = hostOptions.compatWith || null; + ownConfig.debug = debugOptions; + ownConfig.deprecations = Object.assign(DEPRECATIONS, ownConfig.deprecations || {}, hostOptions.deprecations || {}); + ownConfig.features = Object.assign({}, FEATURES); + ownConfig.includeDataAdapter = includeDataAdapter; + ownConfig.packages = MACRO_PACKAGE_FLAGS; + ownConfig.env = getEnv(ownConfig); + + this._emberDataConfig = ownConfig; + return ownConfig; + }, + + included() { + this.configureEmberData(); + return this._super.included.call(this, ...arguments); + }, + + treeForVendor() { + return; + }, + treeForPublic() { + return; + }, + treeForStyles() { + return; + }, + treeForAddonStyles() { + return; + }, + treeForApp() { + return; + }, +}; diff --git a/packages/schema-record/babel.config.js b/packages/schema-record/babel.config.js new file mode 100644 index 00000000000..6ea02d74b8c --- /dev/null +++ b/packages/schema-record/babel.config.js @@ -0,0 +1,13 @@ +const macros = require('@ember-data/private-build-infra/src/v2-babel-build-pack'); + +module.exports = { + plugins: [ + ...macros, + // '@embroider/macros/src/babel/macros-babel-plugin.js', + ['@babel/plugin-transform-runtime', { loose: true }], + ['@babel/plugin-transform-typescript', { allowDeclareFields: true }], + ['@babel/plugin-proposal-decorators', { legacy: true, loose: true }], + ['@babel/plugin-transform-private-methods', { loose: true }], + ['@babel/plugin-transform-class-properties', { loose: true }], + ], +}; diff --git a/packages/schema-record/ember-data-logo-dark.svg b/packages/schema-record/ember-data-logo-dark.svg new file mode 100644 index 00000000000..737a4aa4321 --- /dev/null +++ b/packages/schema-record/ember-data-logo-dark.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/packages/schema-record/ember-data-logo-light.svg b/packages/schema-record/ember-data-logo-light.svg new file mode 100644 index 00000000000..58ac3d4e544 --- /dev/null +++ b/packages/schema-record/ember-data-logo-light.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/packages/schema-record/package.json b/packages/schema-record/package.json new file mode 100644 index 00000000000..6b4ebefbad7 --- /dev/null +++ b/packages/schema-record/package.json @@ -0,0 +1,93 @@ +{ + "name": "@ember-data/schema-record", + "version": "0.0.1-alpha.10", + "description": "Never write a Model again", + "keywords": [ + "ember-addon" + ], + "repository": { + "type": "git", + "url": "git+ssh://git@github.com:emberjs/data.git", + "directory": "packages/schema-record" + }, + "license": "MIT", + "author": "", + "scripts": { + "build": "rollup --config && babel ./addon --out-dir addon --plugins=../private-build-infra/src/transforms/babel-plugin-transform-ext.js", + "start": "rollup --config --watch", + "prepack": "pnpm build", + "prepare": "pnpm build" + }, + "ember-addon": { + "main": "addon-main.js", + "type": "addon", + "version": 1 + }, + "files": [ + "addon-main.js", + "addon", + "README.md", + "LICENSE.md", + "ember-data-logo-dark.svg", + "ember-data-logo-light.svg" + ], + "peerDependencies": { + "@ember-data/graph": "workspace:5.4.0-alpha.10", + "@ember-data/request-utils": "workspace:5.4.0-alpha.10", + "@ember-data/store": "workspace:5.4.0-alpha.10", + "ember-inflector": "^4.0.2" + }, + "dependenciesMeta": { + "@ember-data/private-build-infra": { + "injected": true + }, + "@ember-data/graph": { + "injected": true + }, + "@ember-data/store": { + "injected": true + }, + "@ember-data/request-utils": { + "injected": true, + "optional": true + } + }, + "dependencies": { + "@ember-data/private-build-infra": "workspace:5.4.0-alpha.10", + "@ember/edition-utils": "^1.2.0", + "@embroider/macros": "^1.13.1", + "ember-cli-babel": "^8.0.0" + }, + "devDependencies": { + "@babel/cli": "^7.22.15", + "@babel/core": "^7.22.15", + "@babel/plugin-proposal-decorators": "^7.22.15", + "@babel/plugin-transform-class-properties": "^7.22.5", + "@babel/plugin-transform-private-methods": "^7.22.5", + "@babel/plugin-transform-runtime": "^7.22.15", + "@babel/plugin-transform-typescript": "^7.22.15", + "@babel/preset-env": "^7.22.15", + "@babel/preset-typescript": "^7.22.15", + "@babel/runtime": "^7.22.15", + "@embroider/addon-dev": "^4.1.0", + "@glimmer/component": "^1.1.2", + "@rollup/plugin-babel": "^6.0.3", + "@rollup/plugin-node-resolve": "^15.2.1", + "ember-source": "~5.2.0", + "rollup": "^3.28.1", + "tslib": "^2.6.2", + "typescript": "^5.2.2", + "walk-sync": "^3.0.0", + "webpack": "^5.88.2" + }, + "ember": { + "edition": "octane" + }, + "engines": { + "node": "16.* || >= 18.*" + }, + "volta": { + "extends": "../../package.json" + }, + "packageManager": "pnpm@8.7.1" +} \ No newline at end of file diff --git a/packages/schema-record/rollup.config.mjs b/packages/schema-record/rollup.config.mjs new file mode 100644 index 00000000000..99b6f3ea7d9 --- /dev/null +++ b/packages/schema-record/rollup.config.mjs @@ -0,0 +1,31 @@ +import { Addon } from '@embroider/addon-dev/rollup'; +import babel from '@rollup/plugin-babel'; +import { nodeResolve } from '@rollup/plugin-node-resolve'; + +const addon = new Addon({ + srcDir: 'src', + destDir: 'addon', +}); + +export default { + // This provides defaults that work well alongside `publicEntrypoints` below. + // You can augment this if you need to. + output: addon.output(), + + external: ['@ember-data/store'], + + plugins: [ + // These are the modules that users should be able to import from your + // addon. Anything not listed here may get optimized away. + addon.publicEntrypoints(['index.js']), + + nodeResolve({ extensions: ['.ts', '.js'] }), + babel({ + extensions: ['.ts', '.js'], + babelHelpers: 'runtime', // we should consider "external", + }), + + // Remove leftover build artifacts when starting a new build. + addon.clean(), + ], +}; diff --git a/packages/schema-record/src/index.ts b/packages/schema-record/src/index.ts new file mode 100644 index 00000000000..a0e2ddc696d --- /dev/null +++ b/packages/schema-record/src/index.ts @@ -0,0 +1,6 @@ +import type Store from '@ember-data/store'; +import type { StableRecordIdentifier } from '@ember-data/types/q/identifier'; + +export default class SchemaModel { + constructor(store: Store, identifier: StableRecordIdentifier) {} +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2aae17cdbf8..14553de5be3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1047,6 +1047,92 @@ importers: '@ember/string': injected: true + packages/schema-record: + dependencies: + '@ember-data/private-build-infra': + specifier: workspace:5.4.0-alpha.10 + version: file:packages/private-build-infra + '@ember/edition-utils': + specifier: ^1.2.0 + version: 1.2.0 + '@embroider/macros': + specifier: ^1.12.2 + version: 1.13.1(@babel/core@7.22.15) + ember-cli-babel: + specifier: ^8.0.0 + version: 8.0.0(patch_hash=u45mf2ptxi5n6ldhiqont5zk3y)(@babel/core@7.22.15) + devDependencies: + '@babel/cli': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/core': + specifier: ^7.22.15 + version: 7.22.15(supports-color@8.1.1) + '@babel/plugin-proposal-decorators': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/plugin-transform-class-properties': + specifier: ^7.22.5 + version: 7.22.5(@babel/core@7.22.15) + '@babel/plugin-transform-private-methods': + specifier: ^7.22.5 + version: 7.22.5(@babel/core@7.22.15) + '@babel/plugin-transform-runtime': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/plugin-transform-typescript': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/preset-env': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/preset-typescript': + specifier: ^7.22.15 + version: 7.22.15(@babel/core@7.22.15) + '@babel/runtime': + specifier: ^7.22.15 + version: 7.22.15 + '@embroider/addon-dev': + specifier: ^4.1.0 + version: 4.1.0(rollup@3.28.1) + '@glimmer/component': + specifier: ^1.1.2 + version: 1.1.2(@babel/core@7.22.15) + '@rollup/plugin-babel': + specifier: ^6.0.3 + version: 6.0.3(@babel/core@7.22.15)(rollup@3.28.1) + '@rollup/plugin-node-resolve': + specifier: ^15.2.1 + version: 15.2.1(rollup@3.28.1) + ember-source: + specifier: ~5.2.0 + version: 5.2.0(@babel/core@7.22.15)(@glimmer/component@1.1.2)(webpack@5.88.2) + rollup: + specifier: ^3.28.1 + version: 3.28.1 + tslib: + specifier: ^2.6.2 + version: 2.6.2 + typescript: + specifier: ^5.2.2 + version: 5.2.2 + walk-sync: + specifier: ^3.0.0 + version: 3.0.0 + webpack: + specifier: ^5.88.2 + version: 5.88.2 + dependenciesMeta: + '@ember-data/graph': + injected: true + '@ember-data/private-build-infra': + injected: true + '@ember-data/request-utils': + injected: true + optional: true + '@ember-data/store': + injected: true + packages/serializer: dependencies: '@ember-data/private-build-infra': diff --git a/tsconfig.root.json b/tsconfig.root.json index 8f57f9ab531..3e707207e9d 100644 --- a/tsconfig.root.json +++ b/tsconfig.root.json @@ -57,6 +57,8 @@ "@ember-data/rest/*": ["packages/rest/src/*"], "@ember-data/active-record": ["packages/active-record/src"], "@ember-data/active-record/*": ["packages/active-record/src/*"], + "@ember-data/schema-record": ["packages/schema-record/src"], + "@ember-data/schema-record/*": ["packages/schema-record/src/*"], "@ember-data/experimental-preview-types": ["packages/experimental-preview-types/src"], "@ember-data/experimental-preview-types/*": ["packages/experimental-preview-types/src/*"], "@ember-data/debug": ["packages/debug/addon"], @@ -109,6 +111,7 @@ "packages/adapter/src/**/*", "packages/graph/src/**/*", "packages/active-record/src/**/*", + "packages/schema-record/src/**/*", "packages/rest/src/**/*", "packages/model/src/**/*", "packages/legacy-compat/src/**/*",