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

package/dist/unpkg/prod/declarations/types/schema/fields.type-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/unpkg/prod/declarations/types/schema/schema-service.d.ts

@@ -0,0 +1,380 @@
+import type { CAUTION_MEGA_DANGER_ZONE_Extension, ProcessedExtension } from "../../reactive.js";
+import type { ExtensibleField } from "../../reactive/-private/schema.js";
+import type { ResourceKey } from "../identifier.js";
+import type { ObjectValue } from "../json/raw.js";
+import type { Derivation, HashFn, Transformation } from "./concepts.js";
+import type { ArrayField, CacheableFieldSchema, DerivedField, FieldSchema, GenericField, HashField, IdentityField, LegacyAttributeField, LegacyRelationshipField, ObjectField, Schema, Trait } from "./fields.js";
+export type AttributesSchema = Record<string, LegacyAttributeField>;
+export type RelationshipsSchema = Record<string, LegacyRelationshipField>;
+interface ObjectWithStringTypeProperty {
+	type: string;
+}
+/**
+* The SchemaService provides the ability to query for information about the structure
+* of any resource type.
+*
+* Applications can provide any implementation of the SchemaService they please so long
+* as it conforms to this interface.
+*
+* The design of the service means that schema information could be lazily populated,
+* derived-on-demand, or progressively enhanced during the course of an application's runtime.
+* The primary requirement is merely that any information the service needs to correctly
+* respond to an inquest is available by the time it is asked.
+*
+* The `@warp-drive/legacy/model` package provides an implementation of this service which
+* makes use of your model classes as the source of information to respond to queries
+* about resource schema. While this is useful, this may not be ideal for your application.
+* For instance, Schema information could be sideloaded or pre-flighted for API calls,
+* resulting in no need to bundle and ship potentially large and expensive JSON
+* or large Javascript based Models to pull information from.
+*
+* To register a custom schema implementation, implement the store's `createSchemaService`
+* hook to return an instance of your service.
+*
+* ```ts
+* import { Store } from '@warp-drive/core';
+* import CustomSchemas from './custom-schemas';
+*
+* export default class extends Store {
+*   createSchemaService() {
+*     return new CustomSchemas();
+*   }
+* }
+* ```
+*
+* At runtime, both the `Store` and the `CacheCapabilitiesManager` provide
+* access to this service via the `schema` property.
+*
+* ```ts
+* export default class extends Component {
+*  @service store;
+*
+*  get fields() {
+*    return this.store
+*      .schema
+*      .fields(this.args.dataType);
+*  }
+* }
+* ```
+*
+* @public
+*/
+export interface SchemaService {
+	/**
+	* DEPRECATED - use `hasResource` instead
+	*
+	* Queries whether the SchemaService recognizes `type` as a resource type
+	*
+	* @public
+	* @deprecated - use {@link SchemaService.hasResource | hasResource}
+	*/
+	doesTypeExist?(type: string): boolean;
+	/**
+	* Queries whether the SchemaService recognizes `type` as a resource type
+	*
+	* @public
+	*/
+	hasResource(resource: ObjectWithStringTypeProperty | ResourceKey): boolean;
+	/**
+	* Queries whether the SchemaService recognizes `type` as a resource trait
+	*
+	* @public
+	*/
+	hasTrait(type: string): boolean;
+	/**
+	* Queries whether the given resource has the given trait
+	*
+	* @public
+	*/
+	resourceHasTrait(resource: ObjectWithStringTypeProperty | ResourceKey, trait: string): boolean;
+	/**
+	* Queries for the fields of a given resource type or resource identity.
+	*
+	* Should error if the resource type is not recognized.
+	*
+	* @public
+	*/
+	fields(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, FieldSchema>;
+	/**
+	* Queries for the fields of a given resource type or resource identity.
+	*
+	* Should error if the resource type is not recognized.
+	*
+	* @public
+	*/
+	cacheFields?(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, Exclude<CacheableFieldSchema, IdentityField>>;
+	/**
+	* Returns the transformation registered with the name provided
+	* by `field.type`. Validates that the field is a valid transformable.
+	*
+	* @public
+	*/
+	transformation(field: GenericField | ObjectField | ArrayField | ObjectWithStringTypeProperty): Transformation;
+	/**
+	* Returns the hash function registered with the name provided
+	* by `field.type`. Validates that the field is a valid HashField.
+	*
+	* @public
+	*/
+	hashFn(field: HashField | ObjectWithStringTypeProperty): HashFn;
+	/**
+	* Returns the derivation registered with the name provided
+	* by `field.type`. Validates that the field is a valid DerivedField.
+	*
+	* @public
+	*/
+	derivation(field: DerivedField | ObjectWithStringTypeProperty): Derivation;
+	/**
+	* Returns the schema for the provided resource type.
+	*
+	* @public
+	*/
+	resource(resource: ObjectWithStringTypeProperty | ResourceKey): Schema;
+	/**
+	* Enables registration of multiple Schemas at once.
+	*
+	* This can be useful for either pre-loading schema information
+	* or for registering schema information delivered by API calls
+	* or other sources just-in-time.
+	*
+	* @public
+	*/
+	registerResources(schemas: Schema[]): void;
+	/**
+	* Enables registration of a single Schema representing either
+	* a resource in PolarisMode or LegacyMode or an ObjectSchema
+	* representing an embedded structure in other schemas.
+	*
+	* This can be useful for either pre-loading schema information
+	* or for registering schema information delivered by API calls
+	* or other sources just-in-time.
+	*
+	* @public
+	*/
+	registerResource(schema: Schema): void;
+	/**
+	* Enables registration of a transformation.
+	*
+	* The transformation can later be retrieved by the name
+	* attached to it's `[Type]` property.
+	*
+	* @public
+	*/
+	registerTransformation(transform: Transformation): void;
+	/**
+	* Enables registration of a derivation.
+	*
+	* The derivation can later be retrieved by the name
+	* attached to it's `[Type]` property.
+	*
+	* @public
+	*/
+	registerDerivation<
+		R,
+		T,
+		FM extends ObjectValue | null
+	>(derivation: Derivation<R, T, FM>): void;
+	/**
+	* Enables registration of a hashing function
+	*
+	* The hashing function can later be retrieved by the name
+	* attached to it's `[Type]` property.
+	*
+	* @public
+	*/
+	registerHashFn(hashFn: HashFn): 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;
+	/**
+	* DEPRECATED - use `fields` instead
+	*
+	* Returns definitions for all properties of the specified resource
+	* that are considered "attributes". Generally these are properties
+	* that are not related to book-keeping state on the client and do
+	* not represent a linkage to another resource.
+	*
+	* The return value should be a dictionary of key:value pairs
+	* where the `key` is the attribute or property's name and `value`
+	* is an object with at least the property `name` which should also
+	* match `key`.
+	*
+	* Optionally, this object may also specify `type`, which should
+	* be a string reference to a `transform`, and `options` which
+	* should be dictionary in which any key:value pairs are permissable.
+	*
+	* For instance, when using `@warp-drive/legacy/model`, the following attribute
+	* definition:
+	*
+	* ```ts
+	* class extends Model {
+	*   @attr('string', { defaultValue: 'hello' }) greeting;
+	*   @attr('date') birthday;
+	*   @attr firstName;
+	* }
+	* ```
+	*
+	* Would be returned as:
+	*
+	* ```js
+	* {
+	*   greeting: { name: 'greeting', type: 'string', options: { defaultValue: 'hello' } },
+	*   birthday: { name: 'birthday', type: 'date' },
+	*   firstName: { name: 'firstName' }
+	* }
+	* ```
+	*
+	* @public
+	* @deprecated - use {@link SchemaService.fields | fields}
+	*/
+	attributesDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): AttributesSchema;
+	/**
+	* DEPRECATED - use `fields` instead
+	*
+	* Returns definitions for all properties of the specified resource
+	* that are considered "relationships". Generally these are properties
+	* that represent a linkage to another resource.
+	*
+	* The return value should be a dictionary of key:value pairs
+	* where the `key` is the relationship or property's name and `value`
+	* is an object with at least the following properties:
+	*
+	* - `name` which should also match the `key` used in the dictionary.
+	* - `kind` which should be either `belongsTo` or `hasMany`
+	* - `type` which should be the related resource's string "type"
+	* - `options` which should be a dictionary allowing any key but with
+	*    at least the below keys present.
+	*
+	* - `options.async` a boolean representing whether data for this relationship is
+	*      typically loaded on-demand.
+	* - `options.inverse` a string or null representing the field name / key of the
+	*       corresponding relationship on the inverse resource.
+	*
+	* Additionally the following options properties are optional. See [Polymorphic Relationships](https://rfcs.emberjs.com/id/0793-polymporphic-relations-without-inheritance)
+	*
+	* - `options.polymorphic` a boolean representing whether multiple resource types
+	*    can be used to satisfy this relationship.
+	* - `options.as` a string representing the abstract type that the concrete side of
+	*    a relationship must specify when fulfilling a polymorphic inverse.
+	*
+	* For example, the following Model using @warp-drive/legacy/model would generate this relationships
+	* definition by default:
+	*
+	* ```js
+	* class User extends Model {
+	*   @belongsTo('user', { async: false, inverse: null }) bestFriend;
+	*   @hasMany('user', { async: true, inverse: 'friends' }) friends;
+	*   @hasMany('pet', { async: false, polymorphic: true, inverse: 'owner' }) pets;
+	* }
+	* ```
+	*
+	* Which would be returned as
+	*
+	* ```js
+	* {
+	*   bestFriend: {
+	*     name: 'bestFriend',
+	*     kind: 'belongsTo',
+	*     type: 'user',
+	*     options: {
+	*       async: false,
+	*       inverse: null
+	*     }
+	*   },
+	*   friends: {
+	*     name: 'friends',
+	*     kind: 'hasMany',
+	*     type: 'user',
+	*     options: {
+	*       async: true,
+	*       inverse: 'friends'
+	*     }
+	*   },
+	*   pets: {
+	*     name: 'pets',
+	*     kind: 'hasMany',
+	*     type: 'pet',
+	*     options: {
+	*       async: false,
+	*       polymorphic: true,
+	*       inverse: 'owner'
+	*     }
+	*   },
+	* }
+	* ```
+	*
+	* @public
+	* @deprecated - use {@link SchemaService.fields | fields}
+	*/
+	relationshipsDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): RelationshipsSchema;
+	/**
+	* Returns all known resource types
+	*
+	* @public
+	*/
+	resourceTypes(): Readonly<string[]>;
+	/**
+	* Register an extension for either objects or arrays
+	*
+	* See also {@link CAUTION_MEGA_DANGER_ZONE_Extension}
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_registerExtension?(extension: CAUTION_MEGA_DANGER_ZONE_Extension): void;
+	/**
+	* Retrieve the extension map for a resource
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_resourceExtensions?(resource: ResourceKey | {
+		type: string;
+	}): null | ProcessedExtension["features"];
+	/**
+	* Retrieve the extension map for an object field
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_objectExtensions?(field: ExtensibleField, resolvedType: string | null): null | ProcessedExtension["features"];
+	/**
+	* Retrieve the extension map for an array field
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_arrayExtensions?(field: ExtensibleField): null | ProcessedExtension["features"];
+	/**
+	* Check if a specific extension has been registered previously
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_hasExtension?(ext: {
+		kind: "object" | "array";
+		name: string;
+	}): boolean;
+}
+export {};

package/dist/unpkg/prod/declarations/types/spec/document.d.ts

@@ -0,0 +1,67 @@
+import type { PersistedResourceKey } from "../identifier.js";
+import type { ApiError } from "./error.js";
+import type { Links, Meta, PaginationLinks } from "./json-api-raw.js";
+/**
+* This type represents a raw {json:api} document for a meta-only
+* document returned by a request intended to be inserted into the cache.
+*/
+export interface ResourceMetaDocument {
+	lid?: string;
+	meta: Meta;
+	links?: Links | PaginationLinks;
+}
+/**
+* This type represents a raw {json:api} document for a single resource
+* returned by a request intended to be inserted into the cache.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
+export interface SingleResourceDataDocument<
+	T = PersistedResourceKey,
+	R = PersistedResourceKey
+> {
+	lid?: string;
+	links?: Links | PaginationLinks;
+	meta?: Meta;
+	data: T | null;
+	included?: R[];
+}
+/**
+* This type represents a raw {json:api} document for a resource collection
+* returned by a request intended to be inserted into the cache.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
+export interface CollectionResourceDataDocument<T = PersistedResourceKey> {
+	lid?: string;
+	links?: Links | PaginationLinks;
+	meta?: Meta;
+	data: T[];
+	included?: T[];
+}
+/**
+* A type useful for representing the raw {json:api} documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
+export type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
+/**
+* A type useful for representing the raw {json:api} Error documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveErrorDocument} instead.
+*/
+export interface ResourceErrorDocument {
+	lid?: string;
+	links?: Links | PaginationLinks;
+	meta?: Meta;
+	errors: ApiError[];
+}
+/**
+* A type useful for representing the raw {json:api} documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDocument} instead.
+*/
+export type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;

package/dist/unpkg/prod/declarations/types/spec/error.d.ts

@@ -0,0 +1,18 @@
+import type { Link, Meta } from "./json-api-raw.js";
+export interface ApiError {
+	id?: string;
+	title?: string;
+	detail?: string;
+	links?: {
+		about?: Link;
+		type?: Link;
+	};
+	status?: string;
+	code?: string;
+	source?: {
+		pointer: string;
+		parameter?: string;
+		header?: string;
+	};
+	meta?: Meta;
+}

package/dist/unpkg/prod/declarations/types/spec/json-api-raw.d.ts

@@ -0,0 +1,139 @@
+import type { ArrayValue, ObjectValue } from "../json/raw.js";
+export type Meta = ObjectValue;
+export type LinkObject = {
+	href: string;
+	meta?: Meta;
+};
+export type Link = string | LinkObject;
+export interface Links {
+	related?: Link | null;
+	self?: Link | null;
+}
+export interface PaginationLinks extends Links {
+	first?: Link | null;
+	last?: Link | null;
+	prev?: Link | null;
+	next?: Link | null;
+}
+/**
+* Serves as a reference to a `Resource` but does not contain
+* any data itself.
+*
+* Used to establish relationship linkages between `Resources` and
+* to address data that may not be available synchronously.
+*
+* [JSON:API Spec](https://jsonapi.org/format/#document-resource-identifier-objects)
+*
+* @private
+*/
+export interface ExistingResourceIdentifierObject<T extends string = string> {
+	id: string;
+	type: T;
+	/**
+	* While not officially part of the `JSON:API` spec,
+	* `ember-data` allows the use of `lid` as a local
+	* identifier for a `Resource`.
+	*
+	* @recommended It is best to include the lid used when creating
+	*   a new resource if this is the response to a new resource creation,
+	*   also recommended if this resource type uses secondary indexes.
+	*
+	* Once a `ResourceIdentifierObject` has been seen by the cache, `lid`
+	* should always be present. Only when inbound from the an `API` response
+	* is `lid` considered optional.
+	*
+	* [Identifiers RFC](https://github.com/emberjs/rfcs/blob/main/text/0403-ember-data-identifiers.md#ember-data--identifiers)
+	*
+	*/
+	lid?: string;
+	/**
+	* While valid in the `JSON:API` spec,
+	* `ember-data` ignores `meta` on `ResourceIdentifierObjects`
+	*
+	* @ignored this property goes un-utilized and will be lost
+	* @private
+	*/
+	meta?: Meta;
+}
+/**
+* Serves as a reference to a resource created on the client
+* but not yet persisted.
+*
+* @private
+*/
+export interface NewResourceIdentifierObject<T extends string = string> {
+	/**
+	* Resources newly created on the client _may_
+	* not have an `id` available to them prior
+	* to completion of their first successful `save`.
+	*
+	* `id` will be `null` in this case.
+	*
+	*/
+	id: string | null;
+	type: T;
+	/**
+	* Resources newly created on the client _will always_
+	* have an `lid` assigned immediately and available.
+	*/
+	lid: string;
+}
+export interface ResourceIdentifier {
+	lid: string;
+}
+export type ResourceIdentifierObject<T extends string = string> = ResourceIdentifier | ExistingResourceIdentifierObject<T> | NewResourceIdentifierObject<T>;
+export interface SingleResourceRelationship<T = ExistingResourceIdentifierObject | NewResourceIdentifierObject> {
+	data?: T | null;
+	meta?: Meta;
+	links?: Links;
+}
+export interface CollectionResourceRelationship<T = ExistingResourceIdentifierObject | NewResourceIdentifierObject> {
+	data?: T[];
+	meta?: Meta;
+	links?: PaginationLinks;
+}
+export type InnerRelationshipDocument<T = ExistingResourceIdentifierObject | NewResourceIdentifierObject> = SingleResourceRelationship<T> | CollectionResourceRelationship<T>;
+export type ResourceRelationshipsObject<T = ExistingResourceIdentifierObject | NewResourceIdentifierObject> = Record<string, InnerRelationshipDocument<T>>;
+/**
+* Contains the data for an existing resource in JSON:API format
+*/
+export interface ExistingResourceObject<T extends string = string> extends ExistingResourceIdentifierObject<T> {
+	meta?: Meta;
+	attributes?: ObjectValue;
+	relationships?: ResourceRelationshipsObject<ExistingResourceIdentifierObject>;
+	links?: Links;
+}
+export type NewResourceObject<T extends string = string> = NewResourceIdentifierObject<T> & {
+	meta?: Meta;
+	attributes?: ObjectValue;
+	relationships?: ResourceRelationshipsObject;
+	links?: Links;
+};
+export type ResourceObject<T extends string = string> = ExistingResourceObject<T> | NewResourceObject<T>;
+type Document = {
+	lid?: string;
+	meta?: Meta;
+	included?: ExistingResourceObject[];
+	jsonapi?: ObjectValue;
+	links?: Links | PaginationLinks;
+	errors?: ArrayValue;
+};
+export type EmptyResourceDocument = Document & {
+	data: null;
+};
+export type SingleResourceDocument<T extends string = string> = Document & {
+	data: ExistingResourceObject<T>;
+};
+export type CollectionResourceDocument<T extends string = string> = Document & {
+	data: ExistingResourceObject<T>[];
+};
+/**
+* A (RAW) JSON:API Formatted Document.
+*
+* These documents should follow the JSON:API spec but do not
+* have the same level of guarantees as their `spec` counterparts.
+*
+* @private
+*/
+export type JsonApiDocument<T extends string = string> = EmptyResourceDocument | SingleResourceDocument<T> | CollectionResourceDocument<T>;
+export {};

package/dist/unpkg/prod/declarations/types/symbols.d.ts

@@ -0,0 +1,78 @@
+export declare const RecordStore: "___(unique) Symbol(Store)";
+/**
+* Symbol for the name of a resource, transformation
+* or derivation.
+*
+* ### With Resources
+*
+* This is an optional feature that can be used by
+* record implementations to provide a typescript
+* hint for the type of the resource.
+*
+* When used, WarpDrive APIs can
+* take advantage of this to provide better type
+* safety and intellisense.
+*
+* ### With Derivations
+*
+* Required for derivations registered with
+* `store.registerDerivation(derivation)`.
+*
+* ```ts
+* function concat(record: object, options: ObjectValue | null, prop: string): string {}
+* concat[Name] = 'concat';
+* ```
+*
+* ### With Transforms
+*
+* Required for new-style transformations registered
+* with `store.registerTransform(transform)`.
+*
+* For legacy transforms, if not used,
+* `attr<Transform>('name')` will allow any string name.
+* `attr('name')` will always allow any string name.
+*
+* If used, `attr<Transform>('name')` will enforce
+* that the name is the same as the transform name.
+*
+* @type {Symbol}
+*/
+export declare const Type: "___(unique) Symbol($type)";
+/**
+* Symbol for the type of a resource.
+*
+* This is an optional feature that can be used by
+* record implementations to provide a typescript
+* hint for the type of the resource.
+*
+* When used, WarpDrive APIs can
+* take advantage of this to provide better type
+* safety and intellisense.
+*
+* @type {Symbol}
+*/
+export declare const ResourceType: "___(unique) Symbol($type)";
+/**
+* Symbol for the name of a transform.
+*
+* This is an optional feature that can be used by
+* transform implementations to provide a typescript
+* hint for the name of the transform.
+*
+* If not used, `attr<Transform>('name')` will
+* allow any string name. `attr('name')` will always
+* allow any string name.
+*
+* If used, `attr<Transform>('name')` will enforce
+* that the name is the same as the transform name.
+*
+* @type {Symbol}
+*/
+export declare const TransformName: "___(unique) Symbol($type)";
+/**
+* Symbol for use by builders to indicate the return type
+* generic to use for store.request()
+*
+* @type {Symbol}
+*/
+export declare const RequestSignature: "___(unique) Symbol(RequestSignature)";

package/dist/unpkg/prod/declarations/types/utils.d.ts

@@ -0,0 +1,5 @@
+export type WithPartial<
+	T,
+	K extends keyof T
+> = Omit<T, K> & Partial<Pick<T, K>>;
+export type Mutable<T> = { -readonly [P in keyof T] : T[P] };

package/dist/unpkg/prod/declarations/types.d.ts

@@ -0,0 +1,11 @@
+/**
+* This package provides core types, type-utilities, symbols
+* and constants used across the WarpDrive ecosystem.
+*
+* @module
+*/
+export type { StableRecordIdentifier, ResourceKey } from "./types/identifier.js";
+export type { CacheCapabilitiesManager } from "./store/-types/q/cache-capabilities-manager.js";
+export type { ModelSchema } from "./store/deprecated/-private.js";
+export type { SchemaService } from "./types/schema/schema-service.js";
+export type { BaseFinderOptions, FindRecordOptions, LegacyResourceQuery, QueryOptions, FindAllOptions } from "./store/-types/q/store.js";