@warp-drive/utilities 5.9.0-alpha.2 → 5.9.0-alpha.21

package/declarations/index-BeMAuqgZ.d.ts

@@ -0,0 +1,462 @@
+import { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from "@warp-drive/core/types/params";
+//#region src/index.d.ts
+/**
+ * The global configuration used by {@link buildBaseURL} when a call does
+ * not provide its own `host`/`namespace`. Set via {@link setBuildURLConfig}.
+ *
+ * @public
+ */
+interface BuildURLConfig {
+  /**
+   * The scheme, domain and port (if any) to prefix built URLs with, e.g. `'https://api.example.com'`.
+   */
+  host: string | null;
+  /**
+   * The path segment to insert between `host` and the resource path, e.g. `'api/v1'`.
+   */
+  namespace: string | null;
+}
+/**
+ * Sets the global configuration for `buildBaseURL`
+ * for host and namespace values for the application.
+ *
+ * These values may still be overridden by passing
+ * them to buildBaseURL directly.
+ *
+ * This method may be called as many times as needed.
+ * host values of `''` or `'/'` are equivalent.
+ *
+ * Except for the value of `/` as host, host should not
+ * end with `/`.
+ *
+ * namespace should not start or end with a `/`.
+ *
+ * ```ts
+ * type BuildURLConfig = {
+ *   host: string;
+ *   namespace: string'
+ * }
+ * ```
+ *
+ * Example:
+ *
+ * ```ts
+ * import { setBuildURLConfig } from '@warp-drive/utilities';
+ *
+ * setBuildURLConfig({
+ *   host: 'https://api.example.com',
+ *   namespace: 'api/v1'
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function setBuildURLConfig(config: BuildURLConfig): void;
+/**
+ * {@link buildBaseURL} options for a `findRecord` request.
+ *
+ * @public
+ */
+interface FindRecordUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "findRecord";
+  /**
+   * The type and id of the record to find.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  };
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `query` request.
+ *
+ * @public
+ */
+interface QueryUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "query";
+  /**
+   * The type of the records to query.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+  };
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `findMany` request.
+ *
+ * @public
+ */
+interface FindManyUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "findMany";
+  /**
+   * The type and id of each record to find.
+   */
+  identifiers: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  }[];
+  /**
+   * The path segment for the resource, defaults to the first identifier's `type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `findRelatedCollection` request.
+ *
+ * @public
+ */
+interface FindRelatedCollectionUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "findRelatedCollection";
+  /**
+   * The type and id of the record whose relationship is being fetched.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  };
+  /**
+   * The relationship field name, appended to the resource path.
+   */
+  fieldPath: string;
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `findRelatedRecord` request.
+ *
+ * @public
+ */
+interface FindRelatedResourceUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "findRelatedRecord";
+  /**
+   * The type and id of the record whose relationship is being fetched.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  };
+  /**
+   * The relationship field name, appended to the resource path.
+   */
+  fieldPath: string;
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `createRecord` request.
+ *
+ * @public
+ */
+interface CreateRecordUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "createRecord";
+  /**
+   * The type of the record being created.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+  };
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for an `updateRecord` request.
+ *
+ * @public
+ */
+interface UpdateRecordUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "updateRecord";
+  /**
+   * The type and id of the record being updated.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  };
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for a `deleteRecord` request.
+ *
+ * @public
+ */
+interface DeleteRecordUrlOptions {
+  /**
+   * The request operation this URL is for.
+   */
+  op: "deleteRecord";
+  /**
+   * The type and id of the record being deleted.
+   */
+  identifier: {
+    /**
+     * The resource type.
+     */
+    type: string;
+    /**
+     * The resource id.
+     */
+    id: string;
+  };
+  /**
+   * The path segment for the resource, defaults to `identifier.type` if not provided.
+   */
+  resourcePath?: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * {@link buildBaseURL} options for building a URL directly from a `resourcePath`
+ * without an associated request operation.
+ *
+ * @public
+ */
+interface GenericUrlOptions {
+  /**
+   * The path segment for the resource.
+   */
+  resourcePath: string;
+  /**
+   * Overrides the globally configured host for this call only.
+   */
+  host?: string;
+  /**
+   * Overrides the globally configured namespace for this call only.
+   */
+  namespace?: string;
+}
+/**
+ * The union of all `op`-specific option shapes accepted by {@link buildBaseURL}, one of:
+ *
+ * - {@link FindRecordUrlOptions}
+ * - {@link QueryUrlOptions}
+ * - {@link FindManyUrlOptions}
+ * - {@link FindRelatedCollectionUrlOptions}
+ * - {@link FindRelatedResourceUrlOptions}
+ * - {@link CreateRecordUrlOptions}
+ * - {@link UpdateRecordUrlOptions}
+ * - {@link DeleteRecordUrlOptions}
+ * - {@link GenericUrlOptions}
+ *
+ * @public
+ */
+type UrlOptions = FindRecordUrlOptions | QueryUrlOptions | FindManyUrlOptions | FindRelatedCollectionUrlOptions | FindRelatedResourceUrlOptions | CreateRecordUrlOptions | UpdateRecordUrlOptions | DeleteRecordUrlOptions | GenericUrlOptions;
+/**
+ * Builds a URL for a request based on the provided options.
+ * Does not include support for building query params (see `buildQueryParams`)
+ * so that it may be composed cleanly with other query-params strategies.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { buildBaseURL } from '@warp-drive/utilities';
+ *
+ * const url = buildBaseURL({
+ *   host: 'https://api.example.com',
+ *   namespace: 'api/v1',
+ *   resourcePath: 'emberDevelopers',
+ *   op: 'query',
+ *   identifier: { type: 'ember-developer' }
+ * });
+ *
+ * // => 'https://api.example.com/api/v1/emberDevelopers'
+ * ```
+ *
+ * On the surface this may seem like a lot of work to do something simple, but
+ * it is designed to be composable with other utilities and interfaces that the
+ * average product engineer will never need to see or use.
+ *
+ * A few notes:
+ *
+ * - `resourcePath` is optional, but if it is not provided, `identifier.type` will be used.
+ * - `host` and `namespace` are optional, but if they are not provided, the values globally
+ *    configured via `setBuildURLConfig` will be used.
+ * - `op` is required and must be one of the following:
+ *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'
+ * - Depending on the value of `op`, `identifier` or `identifiers` will be required.
+ *
+ * @public
+ */
+declare function buildBaseURL(urlOptions: UrlOptions): string;
+/**
+ * filter out keys of an object that have falsy values or point to empty arrays
+ * returning a new object with only those keys that have truthy values / non-empty arrays
+ *
+ * @public
+ * @param source object to filter keys with empty values from
+ * @return A new object with the keys that contained empty values removed
+ */
+declare function filterEmpty(source: Record<string, Serializable>): Record<string, Serializable>;
+/**
+ * Sorts query params by both key and value returning a new URLSearchParams
+ * object with the keys inserted in sorted order.
+ *
+ * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
+ *
+ * Options:
+ * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
+ *
+ * 'bracket': appends [] to the key for every value e.g. `&ids[]=1&ids[]=2`
+ * 'indices': appends [i] to the key for every value e.g. `&ids[0]=1&ids[1]=2`
+ * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`
+ * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`
+ *
+ * @public
+ * @return A {@link URLSearchParams} with keys inserted in sorted order
+ */
+declare function sortQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): URLSearchParams;
+/**
+ * Sorts query params by both key and value, returning a query params string
+ *
+ * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
+ *
+ * Options:
+ * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
+ *
+ * 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`
+ * 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`
+ * 'repeat': appends the key for every value e.g. `ids=1&ids=2`
+ * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
+ *
+ * @public
+ * @return A sorted query params string without the leading `?`
+ */
+declare function buildQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): string;
+//#endregion
+export { FindRecordUrlOptions as a, GenericUrlOptions as c, UrlOptions as d, buildBaseURL as f, sortQueryParams as g, setBuildURLConfig as h, FindManyUrlOptions as i, QueryUrlOptions as l, filterEmpty as m, CreateRecordUrlOptions as n, FindRelatedCollectionUrlOptions as o, buildQueryParams as p, DeleteRecordUrlOptions as r, FindRelatedResourceUrlOptions as s, BuildURLConfig as t, UpdateRecordUrlOptions as u };
+//# sourceMappingURL=index-BeMAuqgZ.d.ts.map

package/declarations/index-BeMAuqgZ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BeMAuqgZ.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;UAmBiB;;;;EAIf;;;;EAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Cc,kBAAkB,QAAQ;;;;;;UA6BzB;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;UAOe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;UAQe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;EAIA;;;;;;;;;;;;;;;;;KAkBU,aACR,uBACA,kBACA,qBACA,kCACA,gCACA,yBACA,yBACA,yBACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEY,aAAa,YAAY;;;;;;;;;iBA4HzB,YAAY,QAAQ,eAAe,gBAAgB,eAAe;;;;;;;;;;;;;;;;;;iBA+BlE,gBAAgB,QAAQ,mBAAmB,UAAU,kCAAkC;;;;;;;;;;;;;;;;;iBA4EvF,iBAAiB,QAAQ,mBAAmB,UAAU"}

package/declarations/index.d.ts

@@ -1,208 +1,2 @@
-import type { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from "@warp-drive/core/types/params";
-export interface BuildURLConfig {
-	host: string | null;
-	namespace: string | null;
-}
-/**
-* Sets the global configuration for `buildBaseURL`
-* for host and namespace values for the application.
-*
-* These values may still be overridden by passing
-* them to buildBaseURL directly.
-*
-* This method may be called as many times as needed.
-* host values of `''` or `'/'` are equivalent.
-*
-* Except for the value of `/` as host, host should not
-* end with `/`.
-*
-* namespace should not start or end with a `/`.
-*
-* ```ts
-* type BuildURLConfig = {
-*   host: string;
-*   namespace: string'
-* }
-* ```
-*
-* Example:
-*
-* ```ts
-* import { setBuildURLConfig } from '@warp-drive/utilities';
-*
-* setBuildURLConfig({
-*   host: 'https://api.example.com',
-*   namespace: 'api/v1'
-* });
-* ```
-*
-* @public
-*/
-export declare function setBuildURLConfig(config: BuildURLConfig): void;
-export interface FindRecordUrlOptions {
-	op: "findRecord";
-	identifier: {
-		type: string;
-		id: string;
-	};
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface QueryUrlOptions {
-	op: "query";
-	identifier: {
-		type: string;
-	};
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface FindManyUrlOptions {
-	op: "findMany";
-	identifiers: {
-		type: string;
-		id: string;
-	}[];
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface FindRelatedCollectionUrlOptions {
-	op: "findRelatedCollection";
-	identifier: {
-		type: string;
-		id: string;
-	};
-	fieldPath: string;
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface FindRelatedResourceUrlOptions {
-	op: "findRelatedRecord";
-	identifier: {
-		type: string;
-		id: string;
-	};
-	fieldPath: string;
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface CreateRecordUrlOptions {
-	op: "createRecord";
-	identifier: {
-		type: string;
-	};
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface UpdateRecordUrlOptions {
-	op: "updateRecord";
-	identifier: {
-		type: string;
-		id: string;
-	};
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface DeleteRecordUrlOptions {
-	op: "deleteRecord";
-	identifier: {
-		type: string;
-		id: string;
-	};
-	resourcePath?: string;
-	host?: string;
-	namespace?: string;
-}
-export interface GenericUrlOptions {
-	resourcePath: string;
-	host?: string;
-	namespace?: string;
-}
-export type UrlOptions = FindRecordUrlOptions | QueryUrlOptions | FindManyUrlOptions | FindRelatedCollectionUrlOptions | FindRelatedResourceUrlOptions | CreateRecordUrlOptions | UpdateRecordUrlOptions | DeleteRecordUrlOptions | GenericUrlOptions;
-/**
-* Builds a URL for a request based on the provided options.
-* Does not include support for building query params (see `buildQueryParams`)
-* so that it may be composed cleanly with other query-params strategies.
-*
-* Usage:
-*
-* ```ts
-* import { buildBaseURL } from '@warp-drive/utilities';
-*
-* const url = buildBaseURL({
-*   host: 'https://api.example.com',
-*   namespace: 'api/v1',
-*   resourcePath: 'emberDevelopers',
-*   op: 'query',
-*   identifier: { type: 'ember-developer' }
-* });
-*
-* // => 'https://api.example.com/api/v1/emberDevelopers'
-* ```
-*
-* On the surface this may seem like a lot of work to do something simple, but
-* it is designed to be composable with other utilities and interfaces that the
-* average product engineer will never need to see or use.
-*
-* A few notes:
-*
-* - `resourcePath` is optional, but if it is not provided, `identifier.type` will be used.
-* - `host` and `namespace` are optional, but if they are not provided, the values globally
-*    configured via `setBuildURLConfig` will be used.
-* - `op` is required and must be one of the following:
-*   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'
-* - Depending on the value of `op`, `identifier` or `identifiers` will be required.
-*
-* @public
-*/
-export declare function buildBaseURL(urlOptions: UrlOptions): string;
-/**
-* filter out keys of an object that have falsy values or point to empty arrays
-* returning a new object with only those keys that have truthy values / non-empty arrays
-*
-* @public
-* @param source object to filter keys with empty values from
-* @return A new object with the keys that contained empty values removed
-*/
-export declare function filterEmpty(source: Record<string, Serializable>): Record<string, Serializable>;
-/**
-* Sorts query params by both key and value returning a new URLSearchParams
-* object with the keys inserted in sorted order.
-*
-* Treats `included` specially, splicing it into an array if it is a string and sorting the array.
-*
-* Options:
-* - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
-*
-* 'bracket': appends [] to the key for every value e.g. `&ids[]=1&ids[]=2`
-* 'indices': appends [i] to the key for every value e.g. `&ids[0]=1&ids[1]=2`
-* 'repeat': appends the key for every value e.g. `&ids=1&ids=2`
-* 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`
-*
-* @public
-* @return A {@link URLSearchParams} with keys inserted in sorted order
-*/
-export declare function sortQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): URLSearchParams;
-/**
-* Sorts query params by both key and value, returning a query params string
-*
-* Treats `included` specially, splicing it into an array if it is a string and sorting the array.
-*
-* Options:
-* - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
-*
-* 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`
-* 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`
-* 'repeat': appends the key for every value e.g. `ids=1&ids=2`
-* 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
-*
-* @public
-* @return A sorted query params string without the leading `?`
-*/
-export declare function buildQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): string;
+import { a as FindRecordUrlOptions, c as GenericUrlOptions, d as UrlOptions, f as buildBaseURL, g as sortQueryParams, h as setBuildURLConfig, i as FindManyUrlOptions, l as QueryUrlOptions, m as filterEmpty, n as CreateRecordUrlOptions, o as FindRelatedCollectionUrlOptions, p as buildQueryParams, r as DeleteRecordUrlOptions, s as FindRelatedResourceUrlOptions, t as BuildURLConfig, u as UpdateRecordUrlOptions } from "./index-BeMAuqgZ.js";
+export { BuildURLConfig, CreateRecordUrlOptions, DeleteRecordUrlOptions, FindManyUrlOptions, FindRecordUrlOptions, FindRelatedCollectionUrlOptions, FindRelatedResourceUrlOptions, GenericUrlOptions, QueryUrlOptions, UpdateRecordUrlOptions, UrlOptions, buildBaseURL, buildQueryParams, filterEmpty, setBuildURLConfig, sortQueryParams };