@warp-drive/core 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/dev/declarations/reactive/-private/fields/many-array-manager.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from "../../../index.js";
+import type { RelatedCollection as ManyArray } from "../../../store/-private.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { ResourceKey } from "../../../types/identifier.js";
+import type { ReactiveResource } from "../record.js";
+export interface FindHasManyOptions {
+	reload?: boolean;
+	backgroundReload?: boolean;
+}
+export declare class ManyArrayManager {
+	record: ReactiveResource;
+	store: Store;
+	identifier: ResourceKey;
+	editable: boolean;
+	constructor(record: ReactiveResource, editable: boolean);
+	_syncArray(array: ManyArray): void;
+	reloadHasMany<T>(key: string, options?: FindHasManyOptions): Promise<ManyArray<T>>;
+	mutate(mutation: LocalRelationshipOperation): void;
+}

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

@@ -0,0 +1,5 @@
+import type { Store } from "../../index.js";
+import type { ResourceKey } from "../../types.js";
+import { ReactiveResource } from "./record.js";
+export declare function instantiateRecord(store: Store, identifier: ResourceKey, createArgs?: Record<string, unknown>): ReactiveResource;
+export declare function teardownRecord(record: unknown): void;

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

@@ -0,0 +1,4 @@
+import type { LegacyAliasField, ObjectAliasField, PolarisAliasField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getAliasField(context: KindContext<LegacyAliasField | ObjectAliasField | PolarisAliasField>): unknown;
+export declare function setAliasField(context: KindContext<LegacyAliasField | ObjectAliasField | PolarisAliasField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { ArrayField, SchemaArrayField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getArrayField(context: KindContext<ArrayField | SchemaArrayField>): unknown;
+export declare function setArrayField(context: KindContext<ArrayField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { LegacyAttributeField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getAttributeField(context: KindContext<LegacyAttributeField>): unknown;
+export declare function setAttributeField(context: KindContext<LegacyAttributeField>): boolean;

package/dist/unpkg/dev/declarations/reactive/-private/kind/belongs-to-field.d.ts

@@ -0,0 +1,4 @@
+import type { LegacyBelongsToField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getBelongsToField(context: KindContext<LegacyBelongsToField>): unknown;
+export declare function setBelongsToField(context: KindContext<LegacyBelongsToField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { CollectionField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getCollectionField(context: KindContext<CollectionField>): unknown;
+export declare function setCollectionField(context: KindContext<CollectionField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { DerivedField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getDerivedField(context: KindContext<DerivedField>): unknown;
+export declare function setDerivedField(context: KindContext<DerivedField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { GenericField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getGenericField(context: KindContext<GenericField>): unknown;
+export declare function setGenericField(context: KindContext<GenericField>): boolean;

package/dist/unpkg/dev/declarations/reactive/-private/kind/has-many-field.d.ts

@@ -0,0 +1,4 @@
+import type { LegacyHasManyField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getHasManyField(context: KindContext<LegacyHasManyField>): unknown;
+export declare function setHasManyField(context: KindContext<LegacyHasManyField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { HashField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getHashField(context: KindContext<HashField>): unknown;
+export declare function setHashField(context: KindContext<HashField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { IdentityField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getIdentityField(context: KindContext<IdentityField>): unknown;
+export declare function setIdentityField(context: KindContext<IdentityField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { LocalField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getLocalField(context: KindContext<LocalField>): unknown;
+export declare function setLocalField(context: KindContext<LocalField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { ObjectField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getObjectField(context: KindContext<ObjectField>): unknown;
+export declare function setObjectField(context: KindContext<ObjectField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { ResourceField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getResourceField(context: KindContext<ResourceField>): unknown;
+export declare function setResourceField(context: KindContext<ResourceField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { SchemaArrayField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export { getArrayField as getSchemaArrayField } from "./array-field.js";
+export declare function setSchemaArrayField(context: KindContext<SchemaArrayField>): boolean;

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

@@ -0,0 +1,4 @@
+import type { SchemaObjectField } from "../../../types/schema/fields.js";
+import type { KindContext } from "../default-mode.js";
+export declare function getSchemaObjectField(context: KindContext<SchemaObjectField>): unknown;
+export declare function setSchemaObjectField(context: KindContext<SchemaObjectField>): boolean;

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";