@warp-drive/core 5.8.0-alpha.3 → 5.8.0-alpha.32

package/dist/unpkg/dev/declarations/reactive/-private/record.d.ts

@@ -0,0 +1,83 @@
+import type { ObjectContext, ResourceContext } from "./default-mode.js";
+import { Checkout, Context } from "./symbols.js";
+export interface ReactiveResource {
+	/**
+	* Create an editable copy of the record
+	*
+	* ReactiveResource instances are not editable by default. This method creates an editable copy of the record. To use,
+	* import the `Checkout` symbol from `@warp-drive/core/reactive` and call it on the record.
+	*
+	* ```ts
+	* import { Checkout } from '@warp-drive/core/reactive';
+	*
+	* const record = store.peekRecord('user', '1');
+	* const editableRecord = await record[Checkout]();
+	* ```
+	*
+	* @returns a promise that resolves to the editable record
+	* @throws if the record is already editable or if the record is embedded
+	* @private
+	*/
+	[Checkout]<T>(): Promise<T>;
+}
+/**
+* @private
+*/
+export interface PrivateReactiveResource extends ReactiveResource {
+	/**
+	* @private
+	*/
+	[Context]: ObjectContext | ResourceContext;
+}
+/**
+* A class that uses a the ResourceSchema for a ResourceType
+* and a ResourceKey to transform data from the cache into a rich, reactive
+* object.
+*
+* This class is not directly instantiable. To use it, you should
+* configure the store's `instantiateRecord` and `teardownRecord` hooks
+* with the matching hooks provided by this package.
+*
+* @hideconstructor
+* @public
+*/
+export declare class ReactiveResource {
+	constructor(context: ResourceContext | ObjectContext);
+}
+export declare function _CHECKOUT(record: ReactiveResource): ReactiveResource;
+/**
+* Checkout an immutable resource for editing.
+*
+* {@link ReactiveResource | ReactiveResources} are not editable by default. This method
+* creates an editable copy of the resource.
+*
+* This returns a promise which resolves with the editable
+* version of the resource.
+*
+* ```ts
+* import { checkout } from '@warp-drive/core/reactive';
+*
+* const immutable = store.peekRecord('user', '1');
+* const editable = await checkout(immutable);
+* ```
+*
+* Edits to editable resources will be automatically committed if a new
+* payload from the cache matches their existing value.
+*
+* @public
+*
+* @returns a promise that resolves to the editable resource
+* @throws if the resource is already editable or if resource is an embedded object
+*/
+export declare function checkout<T>(resource: unknown): Promise<T & ReactiveResource>;
+/**
+* Forcibly commit all local changes on an editable resource to
+* the remote (immutable) version.
+*
+* This API should only be used cautiously. Typically a better
+* approach is for either the API or a Handler to reflect saved
+* changes back to update the cache.
+*
+* @public
+*/
+export declare function commit(record: ReactiveResource): Promise<void>;

package/dist/unpkg/dev/declarations/reactive/-private/schema.d.ts

@@ -0,0 +1,326 @@
+import type { SchemaService as SchemaServiceInterface } from "../../types.js";
+import type { ResourceKey } from "../../types/identifier.js";
+import type { ObjectValue, Value } from "../../types/json/raw.js";
+import type { Derivation, HashFn } from "../../types/schema/concepts.js";
+import { type ArrayField, type CacheableFieldSchema, type DerivedField, type FieldSchema, type GenericField, type HashField, type IdentityField, type LegacyAttributeField, type LegacyRelationshipField, type ObjectField, type ObjectSchema, type PolarisResourceSchema, type ResourceSchema, type Trait } from "../../types/schema/fields.js";
+import { Type } from "../../types/symbols.js";
+import type { WithPartial } from "../../types/utils.js";
+import type { ReactiveResource } from "./record.js";
+/**
+* Extensions allow providing non-schema driven behaviors to
+* ReactiveResources, ReactiveArrays, and ReactiveObjects.
+*
+* This should only be used for temporary migration purposes
+* to the new schema system when migrating from either Model
+* or ModelFragments.
+*/
+export interface CAUTION_MEGA_DANGER_ZONE_Extension {
+	/**
+	* Whether this extension extends the behaviors of objects
+	* (both ReactiveObjects and ReactiveResources) or of arrays.
+	*/
+	kind: "object" | "array";
+	/**
+	* The name of the extension, to be used when specifying
+	* either `objectExtensions` or `arrayExtensions` on the
+	* field, ResourceSchema or ObjectSchema
+	*/
+	name: string;
+	/**
+	* An object with iterable keys whose values are the getters
+	* or methods to expose on the object or array.
+	*
+	* or
+	*
+	* A constructable such as a Function or Class whose prototype
+	* will be iterated with getOwnPropertyNames.
+	*
+	* Examples:
+	*
+	* **An Object with methods**
+	*
+	* ```ts
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*    kind: 'object',
+	*    name: 'do-thing-1',
+	*    features: {
+	*      doThingOne(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*      doThingTwo(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*    },
+	*  });
+	* ```
+	*
+	* **A class with getters, methods and decorated fields**
+	*
+	* ```ts
+	* class Features {
+	*   sayHello() {
+	*     return 'hello!';
+	*   }
+	*
+	*   @tracked trackedField = 'initial tracked value';
+	*
+	*   get realName() {
+	*     const self = this as unknown as { name: string };
+	*     return self.name;
+	*   }
+	*   set realName(v: string) {
+	*     const self = this as unknown as { name: string };
+	*     self.name = v;
+	*   }
+	*
+	*   get greeting() {
+	*     const self = this as unknown as { name: string };
+	*     return `hello ${self.name}!`;
+	*   }
+	*
+	*   @computed('name')
+	*   get salutation() {
+	*     const self = this as unknown as { name: string };
+	*     return `salutations ${self.name}!`;
+	*   }
+	*
+	*   @cached
+	*   get helloThere() {
+	*     const self = this as unknown as { name: string };
+	*     return `Well Hello There ${self.name}!`;
+	*   }
+	* }
+	*
+	* // non-decorated fields dont appear on class prototypes as they are instance only
+	* // @ts-expect-error
+	* Features.prototype.untrackedField = 'initial untracked value';
+	*
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*   kind: 'object',
+	*   name: 'my-ext',
+	*   features: Features,
+	* });
+	* ```
+	*
+	*/
+	features: Record<string | symbol, unknown> | Function;
+}
+export type ExtensionDef = {
+	kind: "method";
+	fn: Function;
+} | {
+	kind: "readonly-value";
+	value: unknown;
+} | {
+	kind: "mutable-value";
+	value: unknown;
+} | {
+	kind: "readonly-field";
+	get: () => unknown;
+} | {
+	kind: "mutable-field";
+	get: () => unknown;
+	set: (value: unknown) => void;
+} | {
+	kind: "writeonly-field";
+	set: (value: unknown) => void;
+};
+export interface ProcessedExtension {
+	kind: "object" | "array";
+	name: string;
+	features: Map<string | symbol, ExtensionDef>;
+}
+export interface ExtensibleField {
+	kind: "schema-object" | "schema-array" | "array" | "object" | "hasMany";
+	options?: {
+		objectExtensions?: string[];
+		arrayExtensions?: string[];
+	};
+}
+/**
+* Utility for constructing a ResourceSchema with the recommended
+* fields for the PolarisMode experience.
+*
+* Using this requires registering the PolarisMode derivations
+*
+* ```ts
+* import { registerDerivations } from '@warp-drive/schema-record';
+*
+* registerDerivations(schema);
+* ```
+*
+* @public
+* @param schema
+* @return {PolarisResourceSchema}
+*/
+export declare function withDefaults(schema: WithPartial<PolarisResourceSchema, "identity">): PolarisResourceSchema;
+interface FromIdentityDerivation {
+	(record: ReactiveResource, options: {
+		key: "lid";
+	} | {
+		key: "type";
+	}, key: string): string;
+	(record: ReactiveResource, options: {
+		key: "id";
+	}, key: string): string | null;
+	(record: ReactiveResource, options: {
+		key: "^";
+	}, key: string): ResourceKey;
+	(record: ReactiveResource, options: null, key: string): asserts options;
+	(record: ReactiveResource, options: {
+		key: "id" | "lid" | "type" | "^";
+	} | null, key: string): ResourceKey | string | null;
+	[Type]: "@identity";
+}
+/**
+* A derivation that computes its value from the
+* record's identity.
+*
+* It can be used via a derived field definition like:
+*
+* ```ts
+* {
+*   kind: 'derived',
+*   name: 'id',
+*   type: '@identity',
+*   options: { key: 'id' }
+* }
+* ```
+*
+* Valid keys are `'id'`, `'lid'`, `'type'`, and `'^'`.
+*
+* `^` returns the entire identifier object.
+*
+* @public
+*/
+export declare const fromIdentity: FromIdentityDerivation;
+/**
+* Registers the default derivations for records that want
+* to use the PolarisMode defaults provided by
+*
+* ```ts
+* import { withDefaults } from '@warp-drive/schema-record';
+* ```
+*
+* @public
+*/
+export declare function registerDerivations(schema: SchemaServiceInterface): void;
+interface InternalSchema {
+	original: ResourceSchema | ObjectSchema;
+	finalized: boolean;
+	traits: Set<string>;
+	fields: Map<string, FieldSchema>;
+	cacheFields: Map<string, Exclude<CacheableFieldSchema, IdentityField>>;
+	attributes: Record<string, LegacyAttributeField>;
+	relationships: Record<string, LegacyRelationshipField>;
+}
+export type Transformation<
+	T extends Value = Value,
+	PT = unknown
+> = {
+	serialize(value: PT, options: Record<string, unknown> | null, record: ReactiveResource): T;
+	hydrate(value: T | undefined, options: Record<string, unknown> | null, record: ReactiveResource): PT;
+	defaultValue?(options: Record<string, unknown> | null, identifier: ResourceKey): T;
+	[Type]: string;
+};
+export interface SchemaService {
+	doesTypeExist(type: string): boolean;
+	attributesDefinitionFor(identifier: {
+		type: string;
+	}): InternalSchema["attributes"];
+	relationshipsDefinitionFor(identifier: {
+		type: string;
+	}): InternalSchema["relationships"];
+}
+/**
+* A SchemaService designed to work with dynamically registered schemas.
+*
+* @public
+*/
+export declare class SchemaService implements SchemaServiceInterface {
+	constructor();
+	resourceTypes(): Readonly<string[]>;
+	hasTrait(type: string): boolean;
+	resourceHasTrait(resource: ResourceKey | {
+		type: string;
+	}, trait: string): boolean;
+	transformation(field: GenericField | ObjectField | ArrayField | {
+		type: string;
+	}): Transformation;
+	derivation(field: DerivedField | {
+		type: string;
+	}): Derivation;
+	hashFn(field: HashField | {
+		type: string;
+	}): HashFn;
+	resource(resource: ResourceKey | {
+		type: string;
+	}): ResourceSchema | ObjectSchema;
+	registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void;
+	registerResource(schema: ResourceSchema | ObjectSchema): void;
+	/**
+	* Registers a {@link Trait} for use by resource schemas.
+	*
+	* Traits are re-usable collections of fields that can be composed to
+	* build up a resource schema. Often they represent polymorphic behaviors
+	* a resource should exhibit.
+	*
+	* When we finalize a resource, we walk its traits and apply their fields
+	* to the resource's fields. All specified traits must be registered by
+	* this time or an error will be thrown.
+	*
+	* Traits are applied left-to-right, with traits of traits being applied in the same
+	* way. Thus for the most part, application of traits is a post-order graph traversal
+	* problem.
+	*
+	* A trait is only ever processed once. If multiple traits (A, B, C) have the same
+	* trait (D) as a dependency, D will be included only once when first encountered by
+	* A.
+	*
+	* If a cycle exists such that trait A has trait B which has Trait A, trait A will
+	* be applied *after* trait B in production. In development a cycle error will be thrown.
+	*
+	* Fields are finalized on a "last wins principle". Thus traits appearing higher in
+	* the tree and further to the right of a traits array take precedence, with the
+	* resource's fields always being applied last and winning out.
+	*
+	* @public
+	*/
+	registerTrait(trait: Trait): void;
+	registerTransformation<
+		T extends Value = string,
+		PT = unknown
+	>(transformation: Transformation<T, PT>): void;
+	registerDerivation<
+		R,
+		T,
+		FM extends ObjectValue | null
+	>(derivation: Derivation<R, T, FM>): void;
+	CAUTION_MEGA_DANGER_ZONE_registerExtension(extension: CAUTION_MEGA_DANGER_ZONE_Extension): void;
+	CAUTION_MEGA_DANGER_ZONE_resourceExtensions(resource: ResourceKey | {
+		type: string;
+	}): null | ProcessedExtension["features"];
+	CAUTION_MEGA_DANGER_ZONE_objectExtensions(field: ExtensibleField, resolvedType: string | null): null | ProcessedExtension["features"];
+	CAUTION_MEGA_DANGER_ZONE_arrayExtensions(field: ExtensibleField): null | ProcessedExtension["features"];
+	CAUTION_MEGA_DANGER_ZONE_hasExtension(ext: {
+		kind: "object" | "array";
+		name: string;
+	}): boolean;
+	/**
+	* Registers a {@link HashFn} for use with a {@link HashField} for
+	* either {@link ObjectSchema} identity or polymorphic type calculation.
+	*
+	* @public
+	*/
+	registerHashFn<T extends object>(hashFn: HashFn<T>): void;
+	fields({ type }: {
+		type: string;
+	}): InternalSchema["fields"];
+	cacheFields({ type }: {
+		type: string;
+	}): InternalSchema["cacheFields"];
+	hasResource(resource: {
+		type: string;
+	}): boolean;
+}
+export {};

package/dist/unpkg/dev/declarations/reactive/-private/symbols.d.ts

@@ -0,0 +1,5 @@
+export declare const SOURCE: "___(unique) Symbol(SOURCE)";
+export declare const Destroy: "___(unique) Symbol(Destroy)";
+export declare const Checkout: "___(unique) Symbol(Checkout)";
+export declare const Commit: "___(unique) Symbol(Commit)";
+export declare const Context: "___(unique) Symbol(Context)";

package/dist/unpkg/dev/declarations/reactive/-private.d.ts

@@ -0,0 +1,2 @@
+export { Context } from "./-private/symbols.js";
+export type { PrivateReactiveResource } from "./-private/record.js";

package/dist/unpkg/dev/declarations/reactive.d.ts

@@ -0,0 +1,287 @@
+/**
+* # About
+*
+* This module provides an implementation of reactive objects that a Store may use for creating
+* reactive representations of the raw data for requests, resources and their relationships
+* stored in the cache.
+*
+* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/configuration/)
+* - For defining resource schemas, see [The Schema Guide](/guides/the-manual/schemas/)
+*
+* Any method that returns a record instance will use the `instantiateRecord`
+* hook configured above to instantiate a ReactiveResource once this is in place.
+* After that, its up to you what ReactiveResource can do.
+*
+* ## Modes
+*
+* ReactiveResource has two modes: `legacy` and `polaris`.
+*
+* **LegacyMode** can be used to emulate the behaviors and capabilities of WarpDrive's `Model` class,
+* and because there is little distinction between Model and a ReactiveResource in LegacyMode we refer
+* to both of these approaches as LegacyMode. This mode is the default experience in V5.
+*
+* In LegacyMode:
+*
+* - records are mutable
+* - local changes immediately reflect app wide
+* - records have all the APIs of Model (references, state props, currentState, methods etc)
+* - the continued use of `@warp-drive/legacy` is required (though most imports from it can be removed)
+* - `async: true` relationships are supported (but not recommended outside of [LinksMode](/guides/the-manual/misc/links-mode.md))
+*
+* ---
+*
+* **PolarisMode** is an upcoming suite of features that will become the default experience in V6.
+*
+* In PolarisMode:
+*
+* - records are immutable, unless creating a new resource or explicitly checking out a record for editing
+* - local changes are isolated until committed, displaying only via the editable version of the record
+* - records have a more limited API, focused on only what is in their schema.
+* - some common operations may have more friction to perform because intended utilities are not yet available
+* - `async: true` relationships are not supported (see [LinksMode](/guides/the-manual/misc/links-mode.md))
+* - The `@warp-drive/legacy` package is not required
+*
+* These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
+* a record in LegacyMode and vice-versa. This interopability is true whether the record in LegacyMode is
+* a ReactiveResource or a Model.
+*
+* ---
+*
+* ## Basic Usage
+*
+* ReactiveResource is a reactive object that transforms raw data from an associated
+* cache into reactive data backed by Signals.
+*
+* The shape of the object and the transformation of raw cache data into its
+* reactive form is controlled by a resource schema.
+*
+* For instance, lets say your API is a [{json:api}](https://jsonapi.org) and your store is using
+* the Cache provided by {@link @warp-drive/json-api! | @warp-drive/json-api}, and a request
+* returns the following raw data:
+*
+* ```ts
+* {
+*   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' }}}
+*     }
+*   ]
+* }
+* ```
+*
+* We could describe the `'user'` and `'dog'` resources in the above payload
+* with the following schemas:
+*
+* ```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,
+*         }
+*       }
+*     ]
+*   }
+* ]);
+* ```
+*
+* 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
+* interface Pet {
+*   readonly id: string;
+*   readonly owner: User;
+* }
+*
+* interface Dog extends Pet {
+*   readonly $type: 'dog';
+*   readonly name: string;
+* }
+*
+* interface EditableUser {
+*   readonly $type: 'user';
+*   readonly id: string;
+*   firstName: string;
+*   lastName: string;
+*   readonly name: string;
+*   pets: Array<Dog | Pet>;
+* }
+*
+* 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>
+* }>
+* ```
+*
+* 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.
+*
+* Notice also how we typed this object with `readonly`. This is because while
+* ReactiveResource instances are ***deeply reactive***, they are also ***immutable***.
+*
+* We can mutate a ReactiveResource 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.
+*
+* ```ts
+* import { Checkout } from '@warp-drive/schema-record';
+*
+* const editable = await user[Checkout]();
+* ```
+*
+* ## Utilities
+*
+* ReactiveResource 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
+* import { withDefaults } from '@warp-drive/core/reactive';
+*
+* 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,
+*           linksMode: true,
+*           resetOnRemoteUpdate: false,
+*         }
+*       }
+*     ]
+*   }),
+*   withDefaults({
+*     type: 'dog',
+*     fields: [
+*       { kind: 'field', name: 'name' },
+*       {
+*         kind: 'belongsTo',
+*         name: 'owner',
+*         type: 'user',
+*         options: {
+*           async: false,
+*           inverse: 'pets',
+*           as: 'pet',
+*           linksMode: true,
+*           resetOnRemoteUpdate: false,
+*         }
+*       }
+*     ]
+*   })
+* ]);
+* ```
+*
+* ## Type Support
+*
+* ### Resource Schemas
+*
+* - {@link PolarisResourceSchema}
+* - {@link LegacyResourceSchema}
+* - {@link ObjectSchema}
+*
+* ### Resource Schema Type Utils
+*
+* - {@link resourceSchema}
+* - {@link objectSchema}
+* - {@link isResourceSchema}
+* - {@link isLegacyResourceSchema}
+*
+* ### Field Schemas
+*
+* - {@link LegacyModeFieldSchema}
+* - {@link PolarisModeFieldSchema}
+*
+* @module
+*/
+import { checkout } from "./reactive/-private/record.js";
+export { instantiateRecord, teardownRecord } from "./reactive/-private/hooks.js";
+export { type CAUTION_MEGA_DANGER_ZONE_Extension, type ProcessedExtension, type ExtensionDef, type Transformation, SchemaService, withDefaults, fromIdentity, registerDerivations } from "./reactive/-private/schema.js";
+export { commit, type ReactiveResource } from "./reactive/-private/record.js";
+export { checkout };
+export { Checkout } from "./reactive/-private/symbols.js";
+export { type ReactiveDocument, type ReactiveDataDocument, type ReactiveErrorDocument } from "./reactive/-private/document.js";
+export { getExpensiveRequestSubscription } from "./store/-private/new-core-tmp/expensive-subscription.js";
+export { createRequestSubscription, getRequestState, type RequestState } from "./store/-private.js";
+export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./store/-private/new-core-tmp/promise-state.js";
+export type { LegacyLiveArray } from "./store/-private/record-arrays/legacy-live-array.js";
+export type { LegacyManyArray } from "./store/-private/record-arrays/legacy-many-array.js";
+export type { LegacyQueryArray } from "./store/-private/record-arrays/legacy-query.js";
+export type { ReactiveResourceArray } from "./store/-private/record-arrays/resource-array.js";