@warp-drive/legacy 5.9.0-alpha.21 → 5.9.0-alpha.22

package/dist/model.d.ts

@@ -0,0 +1,404 @@
+import { S as belongsTo, b as RelationshipDecorator, m as PromiseBelongsTo, r as restoreDeprecatedModelRequestBehaviors, t as Model, v as PromiseManyArray, x as RelationshipOptions, y as NoNull } from "./model-62hn5_PD.js";
+import { Store } from "@warp-drive/core";
+import { RelatedCollection as HasMany, RelatedCollection as ManyArray, Store as Store$1 } from "@warp-drive/core/store/-private";
+import { TransformName } from "@warp-drive/core/types/symbols";
+import { SchemaService } from "@warp-drive/core/types";
+import { ArrayValue, ObjectValue, PrimitiveValue } from "@warp-drive/core/types/json/raw";
+import { ResourceKey as ResourceKey$1 } from "@warp-drive/core/types/identifier";
+import { TypeFromInstance } from "@warp-drive/core/types/record";
+import { ArrayField, CacheableFieldSchema, DerivedField, GenericField, HashField, IdentityField, ObjectField, ObjectSchema, ResourceSchema } from "@warp-drive/core/types/schema/fields";
+import { Derivation, HashFn, Transformation } from "@warp-drive/core/types/schema/concepts";
+//#region src/model/-private/util.d.ts
+type DecoratorPropertyDescriptor = (PropertyDescriptor & {
+  initializer?: () => unknown;
+}) | undefined;
+//#endregion
+//#region src/model/-private/attr.d.ts
+/**
+ * Options provided to the attr decorator are
+ * supplied to the associated transform. Any
+ * key-value pair is valid; however, it is highly
+ * recommended to only use statically defined values
+ * that could be serialized to JSON.
+ *
+ * If no transform is provided, the only valid
+ * option is `defaultValue`.
+ *
+ * Examples:
+ *
+ * ```ts
+ * class User extends Model {
+ *  @attr('string', { defaultValue: 'Anonymous' }) name;
+ *  @attr('date', { defaultValue: () => new Date() }) createdAt;
+ *  @attr({ defaultValue: () => ({}) }) preferences;
+ *  @attr('boolean') hasVerifiedEmail;
+ *  @attr address;
+ * }
+ *
+ * @class NOTATHING
+ */
+type AttrOptions<DV = PrimitiveValue | object | unknown[]> = {
+  /**
+   * The default value for this attribute.
+   *
+   * Default values can be provided as a value or a function that will be
+   * executed to generate the default value.
+   *
+   * Default values *should not* be stateful (object, arrays, etc.) as
+   * they will be shared across all instances of the record.
+   *
+   */
+  defaultValue?: DV extends PrimitiveValue ? DV : () => DV;
+  /**
+   * The name of the field as returned by the API and inserted into the
+   * cache if it differs from the name of the decorated property.
+   *
+   * For instance, if the API returns:
+   *
+   * ```ts
+   * {
+   *   attributes: {
+   *     'first-name': 'Chris'
+   *   }
+   * }
+   * ```
+   *
+   * But the app desires to use `record.firstName; // 'Chris'`, then the
+   * property should be named `firstName` and `sourceKey` should be set
+   * to `'first-name'`.
+   *
+   * This option is only needed when the value differs from the property name.
+   */
+  sourceKey?: string;
+};
+type LooseTransformInstance<V, Raw, Name extends string> = {
+  /**
+   * value type must match the return type of the deserialize method
+   *
+   */
+  serialize: (value: V, options: any) => Raw;
+  /**
+   * defaultValue type must match the return type of the deserialize method
+   *
+   */
+  deserialize: (value: Raw, options: any) => V;
+  [TransformName]: Name;
+};
+type TransformHasType = {
+  [TransformName]: string;
+};
+type TypedTransformInstance<V, T extends string> = LooseTransformInstance<V, string, T> | LooseTransformInstance<V, number, T> | LooseTransformInstance<V, boolean, T> | LooseTransformInstance<V, null, T> | LooseTransformInstance<V, ObjectValue, T> | LooseTransformInstance<V, ArrayValue, T> | LooseTransformInstance<V, string | null, T> | LooseTransformInstance<V, number | null, T> | LooseTransformInstance<V, boolean | null, T> | LooseTransformInstance<V, ObjectValue | null, T> | LooseTransformInstance<V, ArrayValue | null, T>;
+type GetMaybeDeserializeValue<T> = T extends {
+  deserialize: (...args: any[]) => unknown;
+} ? ReturnType<T["deserialize"]> : never;
+type TypeFromInstance$1<T> = T extends TransformHasType ? T[typeof TransformName] : never;
+type OptionsFromInstance<T> = TypeFromInstance$1<T> extends never ? never : GetMaybeDeserializeValue<T> extends never ? never : T extends TypedTransformInstance<GetMaybeDeserializeValue<T>, TypeFromInstance$1<T>> ? Parameters<T["deserialize"]>[1] & Parameters<T["serialize"]>[1] & AttrOptions<ReturnType<T["deserialize"]>> : never;
+/**
+ * The return type of `void` is a lie to appease TypeScript. The actual return type
+ * is a descriptor, but typescript incorrectly insists that decorator functions return
+ * `void` or `any`.
+ *
+ */
+type DataDecorator = (target: object, key: string, desc?: DecoratorPropertyDescriptor) => void;
+/**
+`attr` defines an attribute on a {@link Model}.
+By default, attributes are passed through as-is, however you can specify an
+optional type to have the value automatically transformed.
+WarpDrive ships with four basic transform types: `string`, `number`,
+`boolean` and `date`. You can define your own transforms by subclassing
+{@link Transform}.
+
+Note that you cannot use `attr` to define an attribute of `id`.
+
+`attr` takes an optional hash as a second parameter, currently
+supported options are:
+
+- `defaultValue`: Pass a string or a function to be called to set the attribute
+to a default value if and only if the key is absent from the payload response.
+
+Example
+
+```js [app/models/user.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@attr('string') username;
+@attr('string') email;
+@attr('boolean', { defaultValue: false }) verified;
+}
+```
+
+Default value can also be a function. This is useful it you want to return
+a new object for each attribute.
+
+```js [app/models/user.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@attr('string') username;
+@attr('string') email;
+
+@attr({
+defaultValue() {
+return {};
+}
+})
+settings;
+}
+```
+
+The `options` hash is passed as second argument to a transforms'
+`serialize` and `deserialize` method. This allows to configure a
+transformation and adapt the corresponding value, based on the config:
+
+```js [app/models/post.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class PostModel extends Model {
+@attr('text', {
+uppercase: true
+})
+text;
+}
+```
+
+```js [app/transforms/text.js]
+export default class TextTransform {
+serialize(value, options) {
+if (options.uppercase) {
+return value.toUpperCase();
+}
+
+return value;
+}
+
+deserialize(value) {
+return value;
+}
+
+static create() {
+return new this();
+}
+}
+```
+
+@public
+@param type the attribute type
+@param options a hash of options
+*/
+declare function attr(): DataDecorator;
+declare function attr<T>(type: TypeFromInstance$1<T>): DataDecorator;
+declare function attr(type: string): DataDecorator;
+declare function attr(options: AttrOptions): DataDecorator;
+declare function attr<T>(type: TypeFromInstance$1<T>, options?: OptionsFromInstance<T>): DataDecorator;
+declare function attr(type: string, options?: AttrOptions & object): DataDecorator;
+declare function attr(target: object, key: string | symbol, desc?: PropertyDescriptor): void;
+//#endregion
+//#region src/model/-private/has-many.d.ts
+/**
+`hasMany` is used to define Many-To-One and Many-To-Many, and Many-To-None
+relationships on a {@link Model}.
+
+`hasMany` takes a configuration hash as a second parameter, currently
+supported options are:
+
+- `async`: (*required*) A boolean value used to declare whether this is a sync (false) or async (true) relationship.
+- `inverse`: (*required*)  A string used to identify the inverse property on a related model, or `null`.
+- `polymorphic`: (*optional*) A boolean value to mark the relationship as polymorphic
+- `as`: (*optional*) A string used to declare the abstract type "this" record satisfies for polymorphism.
+
+### Examples
+
+To declare a **many-to-one** (or one-to-many) relationship, use
+`belongsTo` in combination with `hasMany`:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'post' }) comments;
+}
+
+
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('post', { async: false, inverse: 'comments' }) post;
+}
+```
+
+To declare a **many-to-many** relationship with managed inverses, use `hasMany` for both sides:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('tag', { async: true, inverse: 'posts' }) tags;
+}
+
+// app/models/tag.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Tag extends Model {
+@hasMany('post', { async: true, inverse: 'tags' }) posts;
+}
+```
+
+To declare a **many-to-many** relationship without managed inverses, use `hasMany` for both sides
+with `null` as the inverse:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('tag', { async: true, inverse: null }) tags;
+}
+
+// app/models/tag.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Tag extends Model {
+@hasMany('post', { async: true, inverse: null }) posts;
+}
+```
+
+To declare a many-to-none relationship between two models, use
+`hasMany` with inverse set to `null` on just one side::
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('category', { async: true, inverse: null }) categories;
+}
+```
+
+#### Sync vs Async Relationships
+
+WarpDrive fulfills relationships using resource data available in
+the cache.
+
+Sync relationships point directly to the known related resources.
+
+When a relationship is declared as async, if any of the known related
+resources have not been loaded, they will be fetched. The property
+on the record when accessed provides a promise that resolves once
+all resources are loaded.
+
+Async relationships may take advantage of links. On access, if the related
+link has not been loaded, or if any known resources are not available in
+the cache, the fresh state will be fetched using the link.
+
+In contrast to async relationship, accessing a sync relationship
+will error on access when any of the known related resources have
+not been loaded.
+
+If you are using `links` with sync relationships, you have to use
+the HasMany reference API to fetch or refresh related resources
+that aren't loaded. For instance, for a `comments` relationship:
+
+```js
+post.hasMany('comments').reload();
+```
+
+#### Polymorphic Relationships
+
+To declare a polymorphic relationship, use `hasMany` with the `polymorphic`
+option set to `true`:
+
+```js
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('commentable', { async: false, inverse: 'comments', polymorphic: true }) parent;
+}
+```
+
+`'commentable'` here is referred to as the "abstract type" for the polymorphic
+relationship.
+
+Polymorphic relationships with `inverse: null` will accept any type of record as their content.
+Polymorphic relationships with `inverse` set to a string will only accept records with a matching
+inverse relationships declaring itself as satisfying the abstract type.
+
+Below, 'as' is used to declare the that 'post' record satisfies the abstract type 'commentable'
+for this relationship.
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'parent', as: 'commentable' }) comments;
+}
+```
+
+Note: every Model that declares an inverse to a polymorphic relationship must
+declare itself exactly the same. This is because polymorphism is based on structural
+traits.
+
+Polymorphic to polymorphic relationships are supported. Both sides of the relationship
+must be declared as polymorphic, and the `as` option must be used to declare the abstract
+type each record satisfies on both sides.
+
+@public
+@param type the name of the related resource
+@param options a hash of options
+*/
+declare function hasMany(): never;
+declare function hasMany(type: string): never;
+declare function hasMany<T>(type: TypeFromInstance<NoNull<T>>, options: RelationshipOptions<T, boolean>): RelationshipDecorator<T>;
+declare function hasMany(type: string, options: RelationshipOptions<unknown, boolean>): RelationshipDecorator<unknown>;
+//#endregion
+//#region src/model/-private/hooks.d.ts
+/**
+ * The `instantiateRecord` hook implementation for use with `Model`. Pass
+ * this to your store's `instantiateRecord` method when configuring the
+ * store to use `Model` for schema/record instantiation.
+ *
+ * @public
+ */
+declare function instantiateRecord(this: Store$1, identifier: ResourceKey$1, createRecordArgs?: {
+  [key: string]: unknown;
+}): Model;
+/**
+ * The `teardownRecord` hook implementation for use with `Model`. Pass this
+ * to your store's `teardownRecord` method when configuring the store to
+ * use `Model` for schema/record instantiation.
+ *
+ * @public
+ */
+declare function teardownRecord(record: Model): void;
+/**
+ * The `modelFor` implementation for use with `Model`, exposed on the store
+ * as `store.modelFor(type)` when the store is configured to use `Model`.
+ * Returns the `Model` subclass registered for the given type, if any.
+ *
+ * @public
+ */
+declare function modelFor<T>(type: TypeFromInstance<T>): typeof Model | void;
+/**
+ * Overload accepting a raw type string instead of a typed record instance.
+ *
+ * @public
+ */
+declare function modelFor(type: string): typeof Model | void;
+//#endregion
+//#region src/model/-private/schema-provider.d.ts
+/**
+ * The `createSchemaService` implementation for use with `Model`. Pass
+ * the result of this to your store's `createSchemaService` method when
+ * configuring the store to use `Model` for schema information.
+ *
+ * @public
+ */
+declare function buildSchema(store: Store): SchemaService;
+//#endregion
+export { type PromiseBelongsTo as AsyncBelongsTo, type PromiseManyArray as AsyncHasMany, type HasMany, type ManyArray, Model, Model as default, attr, belongsTo, buildSchema, hasMany, instantiateRecord, modelFor, restoreDeprecatedModelRequestBehaviors, teardownRecord };
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","names":[],"sources":["../src/model/-private/util.ts","../src/model/-private/attr.ts","../src/model/-private/has-many.ts","../src/model/-private/hooks.ts","../src/model/-private/schema-provider.ts"],"mappings":";;;;;;;;;;;KAKY,+BAA+B;EAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;KC+BtD,YAAY,KAAK;;;;;;;;;;;EAW3B,eAAe,WAAW,iBAAiB,WAAW;;;;;;;;;;;;;;;;;;;;;EAsBtD;;KA8EG,uBAAuB,GAAG,KAAK;;;;;EAOlC,YAAY,OAAO,GAAG,iBAAiB;;;;;EAOvC,cAAc,OAAO,KAAK,iBAAiB;GAE1C,gBAAgB;;KAEP;GAAsB;;KAEtB,uBAAuB,GAAG,oBAClC,uBAAuB,WAAW,KAClC,uBAAuB,WAAW,KAClC,uBAAuB,YAAY,KACnC,uBAAuB,SAAS,KAChC,uBAAuB,GAAG,aAAa,KACvC,uBAAuB,GAAG,YAAY,KACtC,uBAAuB,kBAAkB,KACzC,uBAAuB,kBAAkB,KACzC,uBAAuB,mBAAmB,KAC1C,uBAAuB,GAAG,oBAAoB,KAC9C,uBAAuB,GAAG,mBAAmB;KAIrC,yBAAyB,KAAK;EAAY,iBAAiB;IACnE,WAAW;KAGH,mBAAiB,KAAK,UAAU,mBAAmB,SAAS;KAG5D,oBAAoB,KAC9B,mBAAiB,2BAEb,yBAAyB,2BAEvB,UAAU,uBAAuB,yBAAyB,IAAI,mBAAiB,MAC7E,WAAW,uBAAuB,WAAW,qBAAqB,YAAY,WAAW;;;;;;;KASvF,iBAAiB,gBAAgB,aAAa,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwFjD,QAAQ;iBACR,KAAK,GAAG,MAAM,mBAAiB,KAAK;iBACpC,KAAK,eAAe;iBACpB,KAAK,SAAS,cAAc;iBAC5B,KAAK,GAAG,MAAM,mBAAiB,IAAI,UAAU,oBAAoB,KAAK;iBACtE,KAAK,cAAc,UAAU,uBAAuB;iBACpD,KAAK,gBAAgB,sBAAsB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBC9ClD;iBACA,QAAQ;iBACR,QAAQ,GACtB,MAAM,iBAAiB,OAAO,KAC9B,SAAS,oBAAoB,cAC5B,sBAAsB;iBAKT,QAAQ,cAAc,SAAS,wCAAwC;;;;;;;;;;iBClPvE,kBAAA,MACR,SACN,YAAY,eACZ;;IACC;;;;;;;;iBA+Ba,eAAe,QAAQ;;;;;;;;iBAevB,SAAS,GAAG,MAAM,iBAAiB,YAAY;;;;;;iBAM/C,SAAS,sBAAsB;;;;;;;;;;iBCqM/B,YAAY,OAAO,QAAQ"}