@warp-drive/core 5.6.0-alpha.5 → 5.6.0-beta.0

package/declarations/graph/-private/operations/replace-related-records.d.ts

@@ -0,0 +1,62 @@
+import type { StableRecordIdentifier } from "../../../types.js";
+import type { ReplaceRelatedRecordsOperation } from "../../../types/graph.js";
+import type { Graph } from "../graph.js";
+/*
+case many:1
+========
+In a bi-directional graph with Many:1 edges, adding a value
+results in up-to 3 discrete value transitions, while removing
+a value is only 2 transitions.
+
+For adding C to A
+If: A <<-> B, C <->> D is the initial state,
+and: B <->> A <<-> C, D is the final state
+
+then we would undergo the following transitions.
+
+add C to A
+remove C from D
+add A to C
+
+For removing B from A
+If: A <<-> B, C <->> D is the initial state,
+and: A, B, C <->> D is the final state
+
+then we would undergo the following transitions.
+
+remove B from A
+remove A from B
+
+case many:many
+===========
+In a bi-directional graph with Many:Many edges, adding or
+removing a value requires only 2 value transitions.
+
+For Adding
+If: A<<->>B, C<<->>D is the initial state (double arrows representing the many side)
+And: D<<->>C<<->>A<<->>B is the final state
+
+Then we would undergo two transitions.
+
+add C to A.
+add A to C
+
+For Removing
+If: A<<->>B, C<<->>D is the initial state (double arrows representing the many side)
+And: A, B, C<<->>D is the final state
+
+Then we would undergo two transitions.
+
+remove B from A
+remove A from B
+
+case many:?
+========
+In a uni-directional graph with Many:? edges (modeled in WarpDrive with `inverse:null`) with
+artificial (implicit) inverses, replacing a value results in 2 discrete value transitions.
+This is because a Many:? relationship is effectively Many:Many.
+*/
+export default function replaceRelatedRecords(graph: Graph, op: ReplaceRelatedRecordsOperation, isRemote: boolean): void;
+export declare function addToInverse(graph: Graph, identifier: StableRecordIdentifier, key: string, value: StableRecordIdentifier, isRemote: boolean): void;
+export declare function notifyInverseOfPotentialMaterialization(graph: Graph, identifier: StableRecordIdentifier, key: string, value: StableRecordIdentifier, isRemote: boolean): void;
+export declare function removeFromInverse(graph: Graph, identifier: StableRecordIdentifier, key: string, value: StableRecordIdentifier, isRemote: boolean): void;

package/declarations/graph/-private/operations/update-relationship.d.ts

@@ -0,0 +1,13 @@
+import type { Store } from "../../../index.js";
+import type { StableRecordIdentifier } from "../../../types.js";
+import type { UpdateResourceRelationshipOperation } from "../../../types/cache/operations.js";
+import type { UpdateRelationshipOperation } from "../../../types/graph.js";
+import type { ExistingResourceIdentifierObject, NewResourceIdentifierObject } from "../../../types/spec/json-api-raw.js";
+import type { Graph } from "../graph.js";
+type IdentifierCache = Store["identifierCache"];
+/*
+Updates the "canonical" or "remote" state of a relationship, replacing any existing
+state and blowing away any local changes (excepting new records).
+*/
+export default function updateRelationshipOperation(graph: Graph, op: UpdateRelationshipOperation | UpdateResourceRelationshipOperation): void;
+export declare function upgradeIdentifiers(arr: (ExistingResourceIdentifierObject | NewResourceIdentifierObject | StableRecordIdentifier)[], cache: IdentifierCache): StableRecordIdentifier[];

package/declarations/graph/-private.d.ts

@@ -0,0 +1,13 @@
+import type { Store } from "../index.js";
+import type { CacheCapabilitiesManager } from "../types.js";
+import { Graph } from "./-private/graph.js";
+export { isBelongsTo } from "./-private/-utils.js";
+export type { CollectionEdge } from "./-private/edges/collection.js";
+export type { ResourceEdge } from "./-private/edges/resource.js";
+export type { ImplicitEdge } from "./-private/edges/implicit.js";
+export type { GraphEdge } from "./-private/graph.js";
+export type { UpgradedMeta } from "./-private/-edge-definition.js";
+export type { Graph };
+export declare function peekGraph(store: CacheCapabilitiesManager | Store): Graph | undefined;
+export type peekGraph = typeof peekGraph;
+export declare function graphFor(store: CacheCapabilitiesManager | Store): Graph;

package/declarations/index.d.ts

@@ -1,3 +1,14 @@
-export { Fetch } from './request/-private/fetch.ts';
-export { RequestManager } from './request/-private/manager.ts';
-//# sourceMappingURL=index.d.ts.map
+/**
+* @module
+* @mergeModuleWith <project>
+*/
+import type { ReactiveDocument } from "./reactive/-private/document.js";
+export { Fetch } from "./request/-private/fetch.js";
+export { RequestManager } from "./request/-private/manager.js";
+export { Store, type StoreRequestContext, CacheHandler, type CachePolicy, type StoreRequestInput, recordIdentifierFor, storeFor } from "./store/-private.js";
+/**
+* @deprecated use `ReactiveDocument` instead
+*/
+export type Document<T> = ReactiveDocument<T>;
+export type { DocumentCacheOperation, CacheOperation, NotificationType } from "./store/-private/managers/notification-manager.js";
+export { setIdentifierGenerationMethod, setIdentifierUpdateMethod, setIdentifierForgetMethod, setIdentifierResetMethod, setKeyInfoForResource } from "./store/-private/caches/identifier-cache.js";

package/declarations/reactive/-private/document.d.ts

@@ -0,0 +1,146 @@
+import type { Store } from "../../store/-private/store-service.js";
+import type { StableDocumentIdentifier } from "../../types/identifier.js";
+import type { ImmutableRequestInfo, RequestInfo } from "../../types/request.js";
+import type { ResourceDocument } from "../../types/spec/document.js";
+import type { Meta, PaginationLinks } from "../../types/spec/json-api-raw.js";
+/**
+* A Document is a class that wraps the response content from a request to the API
+* returned by `Cache.put` or `Cache.peek`, converting resource-identifiers into
+* record instances.
+*
+* It is not directly instantiated by the user, and its properties should not
+* be directly modified. Whether individual properties are mutable or not is
+* determined by the record instance itself.
+*
+* @public
+* @hideconstructor
+*/
+export declare class ReactiveDocument<T> {
+	#private;
+	/**
+	* The links object for this document, if any
+	*
+	* e.g.
+	*
+	* ```
+	* {
+	*   self: '/articles?page[number]=3',
+	* }
+	* ```
+	*
+	* @property links
+	* @type {Object|undefined} - a links object
+	* @public
+	*/
+	readonly links?: PaginationLinks;
+	/**
+	* The primary data for this document, if any.
+	*
+	* If this document has no primary data (e.g. because it is an error document)
+	* this property will be `undefined`.
+	*
+	* For collections this will be an array of record instances,
+	* for single resource requests it will be a single record instance or null.
+	*
+	* @property data
+	* @public
+	* @type {Object|Array<object>|null|undefined} - a data object
+	*/
+	readonly data?: T;
+	/**
+	* The errors returned by the API for this request, if any
+	*
+	* @property errors
+	* @public
+	* @type {Object|undefined} - an errors object
+	*/
+	readonly errors?: object[];
+	/**
+	* The meta object for this document, if any
+	*
+	* @property meta
+	* @public
+	* @type {Object|undefined} - a meta object
+	*/
+	readonly meta?: Meta;
+	/**
+	* The identifier associated with this document, if any
+	*
+	* @property identifier
+	* @public
+	* @type {StableDocumentIdentifier|null}
+	*/
+	readonly identifier: StableDocumentIdentifier | null;
+	protected readonly _store: Store;
+	protected readonly _localCache: {
+		document: ResourceDocument;
+		request: ImmutableRequestInfo;
+	} | null;
+	constructor(store: Store, identifier: StableDocumentIdentifier | null, localCache: {
+		document: ResourceDocument;
+		request: ImmutableRequestInfo;
+	} | null);
+	/**
+	* Fetches the related link for this document, returning a promise that resolves
+	* with the document when the request completes. If no related link is present,
+	* will fallback to the self link if present
+	*
+	* @public
+	* @param {Object} options
+	* @return {Promise<Document>}
+	*/
+	fetch(options?: RequestInfo<ReactiveDocument<T>, T>): Promise<ReactiveDocument<T>>;
+	/**
+	* Fetches the next link for this document, returning a promise that resolves
+	* with the new document when the request completes, or null  if there is no
+	* next link.
+	*
+	* @public
+	* @param {Object} options
+	* @return {Promise<Document | null>}
+	*/
+	next(options?: RequestInfo<ReactiveDocument<T>, T>): Promise<ReactiveDocument<T> | null>;
+	/**
+	* Fetches the prev link for this document, returning a promise that resolves
+	* with the new document when the request completes, or null if there is no
+	* prev link.
+	*
+	* @public
+	* @param {Object} options
+	* @return {Promise<Document | null>}
+	*/
+	prev(options: RequestInfo<ReactiveDocument<T>, T>): Promise<ReactiveDocument<T> | null>;
+	/**
+	* Fetches the first link for this document, returning a promise that resolves
+	* with the new document when the request completes, or null if there is no
+	* first link.
+	*
+	* @public
+	* @param {Object} options
+	* @return {Promise<Document | null>}
+	*/
+	first(options: RequestInfo<ReactiveDocument<T>, T>): Promise<ReactiveDocument<T> | null>;
+	/**
+	* Fetches the last link for this document, returning a promise that resolves
+	* with the new document when the request completes, or null if there is no
+	* last link.
+	*
+	* @public
+	* @param {Object} options
+	* @return {Promise<Document | null>}
+	*/
+	last(options: RequestInfo<ReactiveDocument<T>, T>): Promise<ReactiveDocument<T> | null>;
+	/**
+	* Implemented for `JSON.stringify` support.
+	*
+	* Returns the JSON representation of the document wrapper.
+	*
+	* This is a shallow serialization, it does not deeply serialize
+	* the document's contents, leaving that to the individual record
+	* instances to determine how to do, if at all.
+	*
+	* @public
+	* @return
+	*/
+	toJSON(): object;
+}

package/declarations/reactive/-private/fields/compute.d.ts

@@ -0,0 +1,43 @@
+import type { Store, StoreRequestInput } from "../../../index.js";
+import type { Future } from "../../../request.js";
+import { RelatedCollection as ManyArray } from "../../../store/-private.js";
+import type { Cache } from "../../../types/cache.js";
+import type { StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ArrayField, DerivedField, FieldSchema, GenericField, LegacyHasManyField, LocalField, ObjectField, SchemaArrayField, SchemaObjectField } from "../../../types/schema/fields.js";
+import type { Links } from "../../../types/spec/json-api-raw.js";
+import { RecordStore } from "../../../types/symbols.js";
+import { ReactiveResource } from "../record.js";
+import type { SchemaService } from "../schema.js";
+import { Parent } from "../symbols.js";
+import { ManagedArray } from "./managed-array.js";
+import { ManagedObject } from "./managed-object.js";
+export declare const ManagedArrayMap: Map<ReactiveResource, Map<string, ManagedArray | ManyArray>>;
+export declare const ManagedObjectMap: Map<ReactiveResource, Map<string, ManagedObject | ReactiveResource>>;
+export declare function computeLocal(record: typeof Proxy<ReactiveResource>, field: LocalField, prop: string): unknown;
+export declare function peekManagedArray(record: ReactiveResource, field: FieldSchema): ManyArray | ManagedArray | undefined;
+export declare function peekManagedObject(record: ReactiveResource, field: ObjectField): ManagedObject | undefined;
+export declare function peekManagedObject(record: ReactiveResource, field: SchemaObjectField): ReactiveResource | undefined;
+export declare function computeField(schema: SchemaService, cache: Cache, record: ReactiveResource, identifier: StableRecordIdentifier, field: GenericField, prop: string | string[], editable: boolean): unknown;
+export declare function computeArray(store: Store, schema: SchemaService, cache: Cache, record: ReactiveResource, identifier: StableRecordIdentifier, field: ArrayField | SchemaArrayField, path: string[], editable: boolean, legacy: boolean): ManagedArray | null;
+export declare function computeObject(schema: SchemaService, cache: Cache, record: ReactiveResource, identifier: StableRecordIdentifier, field: ObjectField, path: string[], editable: boolean, legacy: boolean): ManagedObject | null;
+export declare function computeSchemaObject(store: Store, cache: Cache, record: ReactiveResource, identifier: StableRecordIdentifier, field: SchemaObjectField, path: string[], legacy: boolean, editable: boolean): ReactiveResource | null;
+export declare function computeAttribute(cache: Cache, identifier: StableRecordIdentifier, prop: string, editable: boolean): unknown;
+export declare function computeDerivation(schema: SchemaService, record: ReactiveResource, identifier: StableRecordIdentifier, field: DerivedField, prop: string): unknown;
+interface ResourceRelationship<T extends ReactiveResource = ReactiveResource> {
+	lid: string;
+	[Parent]: ReactiveResource;
+	[RecordStore]: Store;
+	name: string;
+	data: T | null;
+	links: Links;
+	meta: Record<string, unknown>;
+}
+// TODO probably this should just be a Document
+// but its separate until we work out the lid situation
+declare class ResourceRelationship<T extends ReactiveResource = ReactiveResource> {
+	constructor(store: Store, cache: Cache, parent: ReactiveResource, identifier: StableRecordIdentifier, field: FieldSchema, name: string, editable: boolean);
+	fetch(options?: StoreRequestInput<T, T>): Future<T>;
+}
+export declare function computeResource<T extends ReactiveResource>(store: Store, cache: Cache, parent: ReactiveResource, identifier: StableRecordIdentifier, field: FieldSchema, prop: string, editable: boolean): ResourceRelationship<T>;
+export declare function computeHasMany(store: Store, schema: SchemaService, cache: Cache, record: ReactiveResource, identifier: StableRecordIdentifier, field: LegacyHasManyField, path: string[], editable: boolean, legacy: boolean): ManyArray | null;
+export {};

package/declarations/reactive/-private/fields/extension.d.ts

@@ -0,0 +1,8 @@
+import type { SignalStore, WarpDriveSignal } from "../../../store/-private/new-core-tmp/reactivity/internal.js";
+import type { ExtensionDef } from "../schema.js";
+export type ProxiedMethod = (...args: unknown[]) => unknown;
+export declare function expectNever(value: never): void;
+export declare function isExtensionProp(extensions: Map<string | symbol, ExtensionDef> | null, prop: string | number | symbol): prop is string | symbol;
+export declare function performObjectExtensionGet(receiver: object, extensions: Map<string | symbol, ExtensionDef>, signals: SignalStore, prop: string | symbol): unknown;
+export declare function performExtensionSet(receiver: object, extensions: Map<string | symbol, ExtensionDef>, signals: SignalStore, prop: string | symbol, value: unknown): boolean;
+export declare function performArrayExtensionGet(receiver: object, extensions: Map<string | symbol, ExtensionDef>, signals: SignalStore, prop: string | symbol, _SIGNAL: WarpDriveSignal, boundFns: Map<string | symbol | number, ProxiedMethod>, transaction: (v: boolean) => void): unknown;

package/declarations/reactive/-private/fields/managed-array.d.ts

@@ -0,0 +1,22 @@
+import type { Store } from "../../../index.js";
+import type { WarpDriveSignal } from "../../../store/-private.js";
+import { ARRAY_SIGNAL } from "../../../store/-private.js";
+import type { Cache } from "../../../types/cache.js";
+import type { StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ArrayField, SchemaArrayField } from "../../../types/schema/fields.js";
+import { ReactiveResource } from "../record.js";
+import type { SchemaService } from "../schema.js";
+import { Editable, Legacy, SOURCE } from "../symbols.js";
+export interface ManagedArray extends Omit<Array<unknown>, "[]"> {
+	[SOURCE]: unknown[];
+	identifier: StableRecordIdentifier;
+	path: string[];
+	owner: ReactiveResource;
+	[ARRAY_SIGNAL]: WarpDriveSignal;
+	[Editable]: boolean;
+	[Legacy]: boolean;
+}
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export declare class ManagedArray {
+	constructor(store: Store, schema: SchemaService, cache: Cache, field: ArrayField | SchemaArrayField, data: unknown[], identifier: StableRecordIdentifier, path: string[], owner: ReactiveResource, isSchemaArray: boolean, editable: boolean, legacy: boolean);
+}

package/declarations/reactive/-private/fields/managed-object.d.ts

@@ -0,0 +1,21 @@
+import { OBJECT_SIGNAL, type WarpDriveSignal } from "../../../store/-private.js";
+import type { Cache } from "../../../types/cache.js";
+import type { StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ObjectField, SchemaObjectField } from "../../../types/schema/fields.js";
+import type { ReactiveResource } from "../record.js";
+import type { SchemaService } from "../schema.js";
+import { Editable, EmbeddedPath, Legacy, Parent, SOURCE } from "../symbols.js";
+export declare function notifyObject(obj: ManagedObject): void;
+// const ignoredGlobalFields = new Set<string>(['setInterval', 'nodeType', 'nodeName', 'length', 'document', STRUCTURED]);
+export interface ManagedObject {
+	[SOURCE]: object;
+	[Parent]: StableRecordIdentifier;
+	[EmbeddedPath]: string[];
+	[OBJECT_SIGNAL]: WarpDriveSignal;
+	[Editable]: boolean;
+	[Legacy]: boolean;
+}
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export declare class ManagedObject {
+	constructor(schema: SchemaService, cache: Cache, field: ObjectField | SchemaObjectField, data: object, identifier: StableRecordIdentifier, path: string[], owner: ReactiveResource, editable: boolean, legacy: boolean);
+}

package/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 { StableRecordIdentifier } 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: StableRecordIdentifier;
+	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/declarations/reactive/-private/hooks.d.ts

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

package/declarations/reactive/-private/record.d.ts

@@ -0,0 +1,64 @@
+import type { Store } from "../../index.js";
+import type { StableRecordIdentifier } from "../../types/identifier.js";
+import type { SchemaArrayField, SchemaObjectField } from "../../types/schema/fields.js";
+import { RecordStore } from "../../types/symbols.js";
+import { Checkout, Destroy, Editable, EmbeddedField, EmbeddedPath, Identifier, Legacy, Parent } from "./symbols.js";
+export { Editable, Legacy, Checkout } from "./symbols.js";
+export interface ReactiveResource {
+	[Symbol.toStringTag]: `ReactiveResource<${string}>`;
+	/** @internal */
+	[RecordStore]: Store;
+	/** @internal */
+	[Identifier]: StableRecordIdentifier;
+	/** @internal */
+	[Parent]: StableRecordIdentifier;
+	/** @internal */
+	[EmbeddedField]: SchemaArrayField | SchemaObjectField | null;
+	/** @internal */
+	[EmbeddedPath]: string[] | null;
+	/** @internal */
+	[Editable]: boolean;
+	/** @internal */
+	[Legacy]: boolean;
+	/** @internal */
+	___notifications: object;
+	/** @internal */
+	[Destroy](): void;
+	/**
+	* 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/schema-record` and call it on the record.
+	*
+	* ```ts
+	* import { Checkout } from '@warp-drive/schema-record';
+	*
+	* 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
+	*
+	*/
+	[Checkout]<T>(): Promise<T>;
+}
+/**
+* A class that uses a the ResourceSchema for a ResourceType
+* and a ResouceKey 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
+*/
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export declare class ReactiveResource {
+	constructor(store: Store, identifier: StableRecordIdentifier, Mode: {
+		[Editable]: boolean;
+		[Legacy]: boolean;
+	}, isEmbedded?: boolean, embeddedField?: SchemaArrayField | SchemaObjectField | null, embeddedPath?: string[] | null);
+}