@warp-drive/utilities 5.9.0-beta.0 → 5.9.0-beta.2

package/dist/active-record.d.ts

@@ -0,0 +1,260 @@
+import { ReactiveDataDocument } from "@warp-drive/core/reactive";
+import { TypeFromInstance, TypedRecordInstance } from "@warp-drive/core/types/record";
+import { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOptions, FindRecordOptions, FindRecordRequestOptions, QueryRequestOptions, RemotelyAccessibleIdentifier, UpdateRequestOptions } from "@warp-drive/core/types/request";
+import { QueryParamsSource } from "@warp-drive/core/types/params";
+//#region src/-private/active-record/find-record.d.ts
+/**
+ * Builds request options to fetch a single resource by a known id or identifier
+ * configured for the url and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { findRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const data = await store.request(findRecord('person', '1'));
+ * ```
+ *
+ * **With Options**
+ *
+ * ```ts
+ * import { findRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * **With an Identifier**
+ *
+ * ```ts
+ * import { findRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { findRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @public
+ * @param identifier
+ * @param options
+ */
+declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
+declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
+declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
+declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;
+//#endregion
+//#region src/-private/active-record/query.d.ts
+/**
+ * Builds request options to query for resources, usually by a primary
+ * type, configured for the url and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { query } from '@warp-drive/utilities/active-record';
+ *
+ * const data = await store.request(query('person'));
+ * ```
+ *
+ * **With Query Params**
+ *
+ * ```ts
+ * import { query } from '@warp-drive/utilities/active-record';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { query } from '@warp-drive/utilities/active-record';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] }, { reload: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @public
+ * @param identifier
+ * @param query
+ * @param options
+ */
+declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<ReactiveDataDocument<T[]>>;
+declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;
+//#endregion
+//#region src/-private/active-record/save-record.d.ts
+/**
+ * Builds request options to delete record for resources,
+ * configured for the url, method and header expectations of ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { deleteRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const data = await store.request(deleteRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { deleteRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const options = deleteRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @public
+ * @param record
+ * @param options
+ */
+declare function deleteRecord<T>(record: T, options?: ConstrainedRequestOptions): DeleteRequestOptions<T>;
+declare function deleteRecord(record: unknown, options?: ConstrainedRequestOptions): DeleteRequestOptions;
+/**
+ * Builds request options to create new record for resources,
+ * configured for the url, method and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { createRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.createRecord('person', { name: 'Ted' });
+ * const data = await store.request(createRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { createRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.createRecord('person', { name: 'Ted' });
+ * const options = createRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @public
+ * @param record
+ * @param options
+ */
+declare function createRecord<T>(record: T, options?: ConstrainedRequestOptions): CreateRequestOptions<T>;
+declare function createRecord(record: unknown, options?: ConstrainedRequestOptions): CreateRequestOptions;
+/**
+ * Builds request options to update existing record for resources,
+ * configured for the url, method and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { updateRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const data = await store.request(updateRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `patch` - Allows caller to specify whether to use a PATCH request instead of a PUT request, defaults to `false`.
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { updateRecord } from '@warp-drive/utilities/active-record';
+ *
+ * const person = store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const options = updateRecord(person, { patch: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @public
+ * @param record
+ * @param options
+ */
+declare function updateRecord<T extends TypedRecordInstance, RT extends TypedRecordInstance = T>(record: T, options?: ConstrainedRequestOptions & {
+  patch?: boolean;
+}): UpdateRequestOptions<ReactiveDataDocument<RT>, T>;
+declare function updateRecord(record: unknown, options?: ConstrainedRequestOptions & {
+  patch?: boolean;
+}): UpdateRequestOptions;
+//#endregion
+export { createRecord, deleteRecord, findRecord, query, updateRecord };
+//# sourceMappingURL=active-record.d.ts.map

package/dist/active-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-record.d.ts","names":[],"sources":["../src/-private/active-record/find-record.ts","../src/-private/active-record/query.ts","../src/-private/active-record/save-record.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmEgB,WAAW,GACzB,YAAY,6BAA6B,iBAAiB,KAC1D,UAAU,oBACT,yBAAyB,qBAAqB,IAAI;iBACrC,WACd,YAAY,8BACZ,UAAU,oBACT;iBACa,WAAW,GACzB,MAAM,iBAAiB,IACvB,YACA,UAAU,oBACT,yBAAyB,qBAAqB,IAAI;iBACrC,WAAW,cAAc,YAAY,UAAU,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCxBnE,MAAM,GACpB,MAAM,iBAAiB,IACvB,QAAQ,mBACR,UAAU,4BACT,oBAAoB,qBAAqB;iBAC5B,MACd,cACA,QAAQ,mBACR,UAAU,4BACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCSa,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;iBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEpE,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;iBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEpE,aAAa,UAAU,qBAAqB,WAAW,sBAAsB,GAC3F,QAAQ,GACR,UAAU;EAA8B;IACvC,qBAAqB,qBAAqB,KAAK;iBAClC,aACd,iBACA,UAAU;EAA8B;IACvC"}