@warp-drive-mirror/schema-record 0.0.1 → 0.0.3

package/LICENSE.md

@@ -1,12 +1,23 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (C) 2023 EmberData and WarpDrive contributors
-Copyright (C) 2017-2022 Ember.js contributors
-Portions Copyright (C) 2011-2017 Tilde, Inc. and contributors.
-Portions Copyright (C) 2011 LivingSocial Inc.
+Copyright (c) 2017-2025 Ember.js and contributors
+Copyright (c) 2011-2017 Tilde, Inc. and contributors
+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:
+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 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.
+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.

package/README.md

@@ -1,36 +1,45 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./NCC-1701-a-blue.svg#gh-light-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-light-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
   <img
     class="project-logo"
-    src="./NCC-1701-a.svg#gh-dark-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-dark-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
 </p>
 
-<h3 align="center">Your data, managed.</h3>
+<h3 align="center">Your Data, Managed.</h3>
 <p align="center">🌲 Get back to Nature 🐿️ Or shipping 💚</p>
 
-SchemaRecord is:
 - ⚡️ Fast
 - 📦 Tiny
 - ✨ Optimized
 - 🚀 Scalable
-- :electron: Universal
+- ⚛️ Universal
+- ☢️ Reactive
 
-Never write a Model again.
+SchemaRecord is a reactive object that transforms raw data from an [associated cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts) into reactive data backed by Signals.
 
-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.
+The shape of the object and the transformation of raw cache data into its
+reactive form is controlled by a resource schema.
+
+Resource schemas are simple JSON, allowing them to be defined and delivered from anywhere.
+
+The capabilities that SchemaRecord brings to [*Warp***Drive**](https://github.com/emberjs/data/)
+will simplify even the most complex parts of your app's state management.
 
 ## Installation
 
+Install using your javascript package manager of choice. For instance
+with [pnpm](https://pnpm.io/)
+
 ```cli
-pnpm install @warp-drive-mirror/schema-record
+pnpm add @warp-drive-mirror/schema-record
 ```
 
 **Tagged Releases**
@@ -42,166 +51,259 @@ pnpm install @warp-drive-mirror/schema-record
 - ![NPM LTS 4.12 Version](https://img.shields.io/npm/v/%40warp-drive/schema-record/lts-4-12?label=%40lts-4-12&color=bbbbbb)
 
 
-#### 🔜 Soon 
-Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)
-
-```no-highlight
-pnpm add @warp-drive-mirror/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)
+If this package is how you are first learning about WarpDrive/EmberData, we
+recommend starting with learning about [Requests](https://github.com/emberjs/data/blob/main/packages/request/README.md)
+and the [Store](https://github.com/emberjs/data/blob/main/packages/store/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`.
+SchemaRecord integrates with WarpDrive via the Store's resource lifecycle hooks.
+When WarpDrive needs to create a new record instance to give reactive access to
+a resource in the cache, it calls `instantiateRecord`. When it no longer needs
+that instance, it will call `teardownRecord`.
 
-```ts
+```diff
 import Store from '@ember-data-mirror/store';
-import SchemaRecord from '@warp-drive-mirror/schema-record';
-import Cache from '@ember-data-mirror/json-api';
++import { instantiateRecord, teardownRecord, registerDerivations, SchemaService } from '@warp-drive-mirror/schema-record';
 
-const DestroyHook = Symbol.for('destroy');
+class AppStore extends Store {
 
-export default class extends Store {
-  instantiateRecord(identifier) {
-    return new SchemaRecord(this, identifier);
-  }
++  createSchemaService() {
++    const schema = new SchemaService();
++    registerDerivations(schema);
++    return schema;
++  }
 
-  teardownRecord(record: SchemaRecord): void {
-    record[DestroyHook]();
-  }
++  instantiateRecord(identifier, createArgs) {
++    return instantiateRecord(this, identifier, createArgs);
++  }
+
++  teardownRecord(record) {
++    return teardownRecord(record);
++  }
 }
 ```
 
-## Start Using
-
-Any Store method that returns records will use SchemaRecord once configured as above.
+Any Store API that returns a record instance will use the `instantiateRecord` 
+hook configured above to instantiate a SchemaRecord once this is in place.
 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 `@warp-drive/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
+## Start Using
 
-SchemaRecord is Immutable. This means by design you cannot mutate a SchemaRecord instance.
+### About
 
-How then do you make edits and preserve changes?
+SchemaRecord is a reactive object that transforms raw data from an associated
+cache into reactive data backed by Signals.
 
-### Mutation Workflows
+The shape of the object and the transformation of raw cache data into its
+reactive form is controlled by a resource schema.
 
-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.
+For instance, lets say your API is a [JSON:API](https://jsonapi.org) and your store is using the
+JSONAPICache, and a request returns the following raw data:
 
 ```ts
-const fork = await store.fork();
+{
+  data: {
+    type: 'user',
+    id: '1',
+    attributes: { firstName: 'Chris', lastName: 'Thoburn' },
+    relationships: { pets: { data: [{ type: 'dog', id: '1' }] }}
+  },
+  included: [
+    {
+      type: 'dog',
+      id: '1',
+      attributes: { name: 'Rey' },
+      relationships: { owner: { data: { type: 'user', id: '1' }}}
+    }
+  ]
+}
 ```
 
-Forks are not themselves editable, they are just a pre-requisite.
-There are three ways to get an editable SchemaRecord instance.
+We could describe the `'user'` and `'dog'` resources in the above payload
+with the following schemas:
 
-1. Create a new record with `const editable = fork.createRecord(<type>, 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.
+```ts
+store.schema.registerResources([
+  {
+    type: 'user',
+    identity: { type: '@id', name: 'id' },
+    fields: [
+      {
+        type: '@identity',
+        name: '$type',
+        kind: 'derived',
+        options: { key: 'type' },
+      },
+      { kind: 'field', name: 'firstName' },
+      { kind: 'field', name: 'lastName' },
+      { 
+        kind: 'derived',
+        name: 'name',
+        type: 'concat',
+        options: { fields: ['firstName', 'lastName'], separator: ' ' }
+      },
+      {
+        kind: 'hasMany',
+        name: 'pets',
+        type: 'pet',
+        options: {
+          async: false,
+          inverse: 'owner',
+          polymorphic: true,
+          linksMode: true,
+        }
+      }
+    ]
+  },
+  {
+    type: 'dog',
+    identity: { type: '@id', name: 'id' },
+    fields: [
+      {
+        type: '@identity',
+        name: '$type',
+        kind: 'derived',
+        options: { key: 'type' },
+      },
+      { kind: 'field', name: 'name' },
+      {
+        kind: 'belongsTo',
+        name: 'owner',
+        type: 'user',
+        options: {
+          async: false,
+          inverse: 'pets',
+          as: 'pet',
+          linksMode: true,
+        }
+      }
+    ]
+  }
+]);
+```
 
-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.
+With these schemas in place, the reactive objects that the store would
+provide us whenever we encountered a `'user'` or a `'dog'` would be:
 
 ```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));
+interface Pet {
+  readonly id: string;
+  readonly owner: User;
+}
 
-// reflect the changes back to the original store
-await store.merge(fork);
-```
+interface Dog extends Pet {
+  readonly $type: 'dog';
+  readonly name: string;
+}
 
-> 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.
+interface EditableUser {
+  readonly $type: 'user';
+  readonly id: string;
+  firstName: string;
+  lastName: string;
+  readonly name: string;
+  pets: Array<Dog | Pet>;
+}
 
-### Optimistic UX
+interface User {
+  readonly $type: 'user';
+  readonly id: string;
+  readonly firstName: string;
+  readonly lastName: string;
+  readonly name: string;
+  readonly pets: Readonly<Array<Dog | Pet>>;
+  [Checkout]: Promise<EditableUser>
+}>
+```
 
-```ts
-// get a fork for editing
-const fork = await store.fork();
+Note how based on the schema the reactive object we receive is able to produce
+`name` on user (despite no name field being in the cache), provide `$type`
+pulled from the identity of the resource, and flatten the individual attributes
+and relationships onto the record for easier use.
 
-// create a new record
-const user = fork.createRecord('user', { name: 'Chris' });
+Notice also how we typed this object with `readonly`. This is because while
+SchemaRecord instances are ***deeply reactive***, they are also ***immutable***.
 
-// reflect the (dirty) changes back to the original store
-await store.merge(fork);
+We can mutate a SchemaRecord only be explicitly asking permission to do so, and
+in the process gaining access to an editable copy. The immutable version will
+not show any in-process edits made to this editable copy.
 
-// save the record
-await fork.request(createRecord(user));
+```ts
+import { Checkout } from '@warp-drive-mirror/schema-record';
 
-// reflect the (clean) changes back to the original store
-await store.merge(fork);
+const editable = await user[Checkout]();
 ```
 
-## Schema Format
+### Utilities
 
-The schema format is the array representation of a Map structure. From which
-we will populate or append to a Map!
+SchemaRecord provides a schema builder that simplifies setting up a couple of
+conventional fields like identity and `$type`. We can rewrite the schema
+definition above using this utility like so:
 
 ```ts
-[
-  [ 'user', <user-schema> ],
-  [ 'company', <company-schema> ],
-]
+import { withDefaults } from '@warp-drive-mirror/schema-record';
+
+store.schema.registerResources([
+  withDefaults({
+    type: 'user',
+    fields: [
+      { kind: 'field', name: 'firstName' },
+      { kind: 'field', name: 'lastName' },
+      { 
+        kind: 'derived',
+        name: 'name',
+        type: 'concat',
+        options: { fields: ['firstName', 'lastName'], separator: ' ' }
+      },
+      {
+        kind: 'hasMany',
+        name: 'pets',
+        type: 'pet',
+        options: {
+          async: false,
+          inverse: 'owner',
+          polymorphic: true
+        }
+      }
+    ]
+  }),
+  withDefaults({
+    type: 'dog',
+    fields: [
+      { kind: 'field', name: 'name' },
+      {
+        kind: 'belongsTo',
+        name: 'owner',
+        type: 'user',
+        options: {
+          async: false,
+          inverse: 'pets',
+          as: 'pet',
+        }
+      }
+    ]
+  })
+]);
 ```
 
-It follows this signature:
+Additionally, `@warp-drive-mirror/core-types` provides several utilities for type-checking and narrowing schemas.
 
-```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<string, unknown>;
-};
-
-type ResourceSchema = Array<[FieldName, FieldDef]>
-type Schemas = Array<[ResourceType, ResourceSchema]>
-```
+- (type) [PolarisResourceSchema]()
+- (type) [LegacyResourceSchema]()
+- (type) [ObjectSchema]()
+- [resourceSchema]()
+- [objectSchema]()
+- [isResourceSchema]()
+- [isLegacyResourceSchema]()
+
+
+### Field Schemas
 
-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.
+For the full range of available schema capabilities, see [Field Schemas](../core-types/src/schema/fields.ts)
 
 
 ### ♥️ Credits

package/dist/-private.js

@@ -0,0 +1 @@
+export { E as Editable, L as Legacy } from "./symbols-DqoS4ybV.js";

package/dist/-private.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"-private.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}