@ember-data/store 5.4.0-alpha.30 → 5.4.0-alpha.32

package/unstable-preview-types/-types/q/schema-service.d.ts

@@ -0,0 +1,212 @@
+/**
+  @module @ember-data/store
+*/
+import type { RecordIdentifier } from '@warp-drive/core-types/identifier';
+import type { AttributesSchema, RelationshipsSchema } from '@warp-drive/core-types/schema';
+export interface FieldSchema {
+    type: string | null;
+    name: string;
+    kind: 'attribute' | 'hasMany' | 'belongsTo' | 'field' | 'resource' | 'collection' | 'derived' | 'object' | 'array' | '@id' | '@local';
+    options?: Record<string, unknown>;
+}
+/**
+ * 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 `@ember-data/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, extend the store service or
+ * lookup and register the schema service first thing on app-boot. Example below
+ * shows extending the service.
+ *
+ * ```ts
+ * import Store from '@ember-data/store';
+ * import CustomSchemas from './custom-schemas';
+ *
+ * export default class extends Store {
+ *   constructor(...args) {
+ *     super(...args);
+ *     this.registerSchema(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 attributes() {
+ *    return this.store
+ *      .schema
+ *      .attributesDefinitionFor(this.args.dataType);
+ *  }
+ * }
+ * ```
+ *
+ * Note: there can only be one schema service registered at a time.
+ * If you register a new schema service, the old one will be replaced.
+ *
+ * If you would like to inherit from another schema service, you can do so by
+ * using typical class inheritance patterns OR by accessing the existing
+ * schema service at runtime before replacing it with your own, and then
+ * having your own delegate to it when needed.
+ *
+ * @class <Interface> SchemaService
+ * @public
+ */
+export interface SchemaService {
+    /**
+     * Queries whether the schema-definition-service recognizes `type` as a resource type
+     *
+     * @method doesTypeExist
+     * @public
+     * @param {string} type
+     * @return {boolean}
+     */
+    doesTypeExist(type: string): boolean;
+    fields({ type }: {
+        type: string;
+    }): Map<string, FieldSchema>;
+    /**
+     * 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 `@ember-data/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' }
+     * }
+     * ```
+     *
+     * @method attributesDefinitionFor
+     * @public
+     * @param {RecordIdentifier|{ type: string }} identifier
+     * @return {AttributesSchema}
+     */
+    attributesDefinitionFor(identifier: RecordIdentifier | {
+        type: string;
+    }): AttributesSchema;
+    /**
+     * 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 @ember-data/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'
+     *     }
+     *   },
+     * }
+     * ```
+     *
+     * @method relationshipsDefinitionFor
+     * @public
+     * @param {RecordIdentifier|{ type: string }} identifier
+     * @return {RelationshipsSchema}
+     */
+    relationshipsDefinitionFor(identifier: RecordIdentifier | {
+        type: string;
+    }): RelationshipsSchema;
+}
+//# sourceMappingURL=schema-service.d.ts.map

package/unstable-preview-types/-types/q/schema-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-service.d.ts","sourceRoot":"","sources":["../../../src/-types/q/schema-service.ts"],"names":[],"mappings":"AAAA;;EAEE;AAEF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EACA,WAAW,GACX,SAAS,GACT,WAAW,GACX,OAAO,GACP,UAAU,GACV,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,OAAO,GACP,KAAK,GACL,QAAQ,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAErC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,uBAAuB,CAAC,UAAU,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,CAAC;IAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6EG;IACH,0BAA0B,CAAC,UAAU,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,mBAAmB,CAAC;CAClG"}

package/unstable-preview-types/-types/q/store.d.ts

@@ -0,0 +1,15 @@
+import type { Value } from '@warp-drive/core-types/json/raw';
+export interface BaseFinderOptions {
+    reload?: boolean;
+    backgroundReload?: boolean;
+    include?: string | string[];
+    adapterOptions?: Record<string, unknown>;
+}
+export interface FindRecordOptions extends BaseFinderOptions {
+    preload?: Record<string, Value>;
+}
+export type QueryOptions = {
+    [K in string | 'adapterOptions']?: K extends 'adapterOptions' ? Record<string, unknown> : unknown;
+};
+export type FindAllOptions = BaseFinderOptions;
+//# sourceMappingURL=store.d.ts.map

package/unstable-preview-types/-types/q/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/-types/q/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AACD,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,YAAY,GAAG;KACxB,CAAC,IAAI,MAAM,GAAG,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;CAClG,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC"}

package/unstable-preview-types/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * <p align="center">
+ *   <img
+ *     class="project-logo"
+ *     src="https://raw.githubusercontent.com/emberjs/data/4612c9354e4c54d53327ec2cf21955075ce21294/ember-data-logo-light.svg#gh-light-mode-only"
+ *     alt="EmberData Store"
+ *     width="240px"
+ *     title="EmberData Store"
+ *     />
+ * </p>
+ *
+ * This package provides [*Ember***Data**](https://github.com/emberjs/data/)'s `Store` class.
+ *
+ * A [Store](https://api.emberjs.com/ember-data/release/classes/Store) coordinates interaction between your application, a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache),
+ * and sources of data (such as your API or a local persistence layer) accessed via a [RequestManager](https://github.com/emberjs/data/tree/main/packages/request).
+ *
+ * Optionally, a Store can be configured to hydrate the response data into rich presentation classes.
+ *
+ * ## Installation
+ *
+ * If you have installed `ember-data` then you already have this package installed.
+ * Otherwise you can install it using your javascript package manager of choice.
+ * For instance with [pnpm](https://pnpm.io/)
+ *
+ * ```
+ * pnpm add @ember-data/store
+ * ```
+ *
+ * After installing you will want to configure your first `Store`. Read more below
+ * for how to create and configure stores for your application.
+ *
+ *
+ * ## 🔨 Creating A Store
+ *
+ * To use a `Store` we will need to do few things: add a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache)
+ * to store data **in-memory**, add a [Handler](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache) to fetch data from a source,
+ * and implement `instantiateRecord` to tell the store how to display the data for individual resources.
+ *
+ * > **Note**
+ * > If you are using the package `ember-data` then a JSON:API cache, RequestManager, LegacyNetworkHandler,
+ * > and `instantiateRecord` are configured for you by default.
+ *
+ * ### Configuring A Cache
+ *
+ * To start, let's install a [JSON:API](https://jsonapi.org/) cache. If your app uses `GraphQL` or `REST` other
+ * caches may better fit your data. You can author your own cache by creating one that
+ * conforms to the [spec](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache).
+ *
+ * The package `@ember-data/json-api` provides a [JSON:API](https://jsonapi.org/) cache we can use.
+ * After installing it, we can configure the store to use this cache.
+ *
+ * ```js
+ * import Store from '@ember-data/store';
+ * import Cache from '@ember-data/json-api';
+ *
+ * class extends Store {
+ *   createCache(storeWrapper) {
+ *     return new Cache(storeWrapper);
+ *   }
+ * }
+ * ```
+ *
+ * Now that we have a `cache` let's setup something to handle fetching
+ * and saving data via our API.
+ *
+ * > **Note**
+ * > The `ember-data` package automatically includes and configures
+ * > the `@ember-data/json-api` cache for you.
+ *
+ * ### Handling Requests
+ *
+ * When *Ember***Data** needs to fetch or save data it will pass that request to your application's `RequestManager` for fulfillment. How this fulfillment occurs (in-memory, device storage, via single or multiple API requests, etc.) is then up to the registered request handlers.
+ *
+ * To start, let's install the `RequestManager` from `@ember-data/request` and the basic `Fetch` handler from ``@ember-data/request/fetch`.
+ *
+ * > **Note**
+ * > If your app uses `GraphQL`, `REST` or different conventions for `JSON:API` than your cache expects, other handlers may better fit your data. You can author your own handler by creating one that conforms to the [handler interface](https://github.com/emberjs/data/tree/main/packages/request#handling-requests).
+ *
+ * ```ts
+ * import Store from '@ember-data/store';
+ * import RequestManager from '@ember-data/request';
+ * import Fetch from '@ember-data/request/fetch';
+ *
+ * export default class extends Store {
+ *   constructor() {
+ *     super(...arguments);
+ *     this.requestManager = new RequestManager();
+ *     this.requestManager.use([Fetch]);
+ *   }
+ * }
+ * ```
+ *
+ * **Using RequestManager as a Service**
+ *
+ * Alternatively if you have configured the `RequestManager` to be a service you may re-use it.
+ *
+ * *app/services/request.js*
+ * ```ts
+ * import RequestManager from '@ember-data/request';
+ * import Fetch from '@ember-data/request/fetch';
+ *
+ * export default class extends RequestManager {
+ *   constructor(createArgs) {
+ *     super(createArgs);
+ *     this.use([Fetch]);
+ *   }
+ * }
+ * ```
+ *
+ * *app/services/store.js*
+ * ```ts
+ * import Store from '@ember-data/store';
+ * import { service } from '@ember/service';
+ *
+ * export default class extends Store {
+ *   @service('request') requestManager
+ * }
+ * ```
+ *
+ *
+ * ### Presenting Data from the Cache
+ *
+ * Now that we have a source and a cach for our data, we need to configure how
+ * the Store delivers that data back to our application. We do this via the hook
+ * [instantiateRecord](https://api.emberjs.com/ember-data/release/classes/Store/methods/instantiateRecord%20(hook)?anchor=instantiateRecord%20(hook)),
+ * which allows us to transform the data for a resource before handing it to the application.
+ *
+ * A naive way to present the data would be to return it as JSON. Typically instead
+ * this hook will be used to add reactivity and make each unique resource a singleton,
+ * ensuring that if the cache updates our presented data will reflect the new state.
+ *
+ * Below is an example of using the hooks `instantiateRecord` and a `teardownRecord`
+ * to provide minimal read-only reactive state for simple resources.
+ *
+ * ```ts
+ * import Store, { recordIdentifierFor } from '@ember-data/store';
+ * import { TrackedObject } from 'tracked-built-ins';
+ *
+ * class extends Store {
+ *   instantiateRecord(identifier) {
+ *     const { cache, notifications } = this;
+ *
+ *     // create a TrackedObject with our attributes, id and type
+ *     const record = new TrackedObject(Object.assign({}, cache.peek(identifier)));
+ *     record.type = identifier.type;
+ *     record.id = identifier.id;
+ *
+ *     notifications.subscribe(identifier, (_, change) => {
+ *       if (change === 'attributes') {
+ *         Object.assign(record, cache.peek(identifier));
+ *       }
+ *     });
+ *
+ *     return record;
+ *   }
+ * }
+ * ```
+ *
+ * Because `instantiateRecord` is opaque to the nature of the record, an implementation
+ * can be anything from a fairly simple object to a robust proxy that intelligently links
+ * together associated records through relationships.
+ *
+ * This also enables creating a record that separates `edit` flows from `create` flows
+ * entirely. A record class might choose to implement a `checkout`method that gives access
+ * to an editable instance while the primary record continues to be read-only and reflect
+ * only persisted (non-mutated) state.
+ *
+ * Typically you will choose an existing record implementation such as `@ember-data/model`
+ * for your application.
+ *
+ * Because of the boundaries around instantiation and the cache, record implementations
+ * should be capable of interop both with each other and with any `Cache`. Due to this,
+ * if needed an application can utilize multiple record implementations and multiple cache
+ * implementations either to support enhanced features for only a subset of records or to
+ * be able to incrementally migrate from one record/cache to another record or cache.
+ *
+ * > **Note**
+ * > The `ember-data` package automatically includes the `@ember-data/model`
+ * > package and configures it for you.
+ *
+ * @module @ember-data/store
+ * @main @ember-data/store
+ */
+export { Store as default, CacheHandler, type LifetimesService, setIdentifierGenerationMethod, setIdentifierUpdateMethod, setIdentifierForgetMethod, setIdentifierResetMethod, recordIdentifierFor, storeFor, } from './-private';
+//# sourceMappingURL=index.d.ts.map

package/unstable-preview-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsLG;AAEH,OAAO,EACL,KAAK,IAAI,OAAO,EAChB,YAAY,EACZ,KAAK,gBAAgB,EACrB,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,EACnB,QAAQ,GACT,MAAM,YAAY,CAAC"}