@warp-drive/core 5.8.0-alpha.9 → 5.8.0-beta.1

package/dist/unpkg/dev/types/record.js

@@ -0,0 +1,191 @@
+/**
+ * Records may be anything, They don't even
+ * have to be objects.
+ *
+ * Whatever they are, if they have a Type
+ * property, that property will be used by WarpDrive
+ * and WarpDrive to provide better type safety and
+ * intellisense.
+ *
+ * @class TypedRecordInstance
+ */
+
+/**
+ * A type utility that extracts the Type if available,
+ * otherwise it returns never.
+ *
+ */
+
+/**
+ * A type utility that extracts the Type if available,
+ * otherwise it returns string
+ *
+ */
+
+/**
+ * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.
+ *
+ * Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which
+ * implement includes will not allow cyclical include paths, and will collapse includes by type.
+ *
+ * This follows closer to the JSON:API fields spec than to the includes spec in nature, but in
+ * practice it is so impracticle for an API to allow z-algo include paths that this is probably
+ * reasonable.
+ *
+ * We may need to revisit this in the future, opting to either make this restriction optional or
+ * to allow for other strategies.
+ *
+ * There's a 90% chance this particular implementation belongs being in the JSON:API package instead
+ * of core-types, but it's here for now.
+ *
+ */
+
+/**
+ * A utility that provides the union of all ResourceName for all potential
+ * includes for the given TypedRecordInstance.
+ *
+ */
+
+// ToPaths<ExpandIgnore<T, true>, false>;
+
+/**
+ * A utility that provides the union type of all valid include paths for the given
+ * TypedRecordInstance.
+ *
+ * Cyclical paths are filtered out.
+ *
+ */
+
+function createIncludeValidator() {
+  return function validateIncludes(includes) {
+    return includes;
+  };
+}
+
+/**
+ * A utility that takes two types, K and T, and produces a new type that is a "mask" of T based on K.
+ *
+ * That's a mouthful, so let's break it down:
+ *
+ * Let's say you have a User type and an Address type.
+ *
+ * ```ts
+ * interface Address {
+ *   street: string;
+ *   city: string;
+ *   state: string;
+ *   zip: string;
+ * }
+ *
+ * interface User {
+ *   name: string;
+ *   title: string;
+ *   address: Address;
+ * }
+ * ```
+ *
+ * Now, imagine you want to load a preview of the user with some information about their address,
+ * but you don't want to load the entire user or address. You probably want to still ensure
+ * the type of the data you do load matches the underlying Address and User types, but doesn't
+ * include everything.
+ *
+ * If you did this manually, you might do something like this:
+ *
+ * ```ts
+ * interface UserPreview {
+ *   name: string;
+ *   address: AddressPreview;
+ * }
+ *
+ * interface AddressPreview {
+ *   city: string;
+ * }
+ * ```
+ *
+ * From a TypeScript performance perspective, this is the best way to approach these preview
+ * types, but this is also tedious and error-prone, especially if the User or Address types change.
+ *
+ * For Address, we could create a validated type using `Pick`:
+ *
+ * ```ts
+ * type AddressPreview = Pick<Address, 'city'>;
+ * ```
+ *
+ * This ensures that if the Address type changes, our AddressPreview will still be valid.
+ * However, for UserPreview, we can't just use `Pick` because the `address` property is of type `Address`,
+ * not `AddressPreview`. This is where the `Mask` type comes in.
+ *
+ * With `Mask`, we define the `UserPreview` in two parts
+ * - first, we define the subset of fields we want to include from `User`, using `Pick` or an interface.
+ * - then, we use `Mask` to replace the related types of fields like Address with their more limited subset.
+ *
+ * Here's how we can do it:
+ *
+ * ```ts
+ * // First, we define the base of UserPreview with Pick
+ * type UserPreviewBase = Pick<User, 'name' | 'address'>;
+ * // Then, we use Mask to replace Address with AddressPreview
+ * type UserPreview = Mask<{ address: AddressPreview }, UserPreviewBase>;
+ * ```
+ *
+ * Now, `UserPreview` will have the `name` field from `User` and the `address` field will be of type `AddressPreview`.
+ * This way, if the `User` or `Address` types change, TypeScript will ensure that our `UserPreview` and `AddressPreview`
+ * types remain valid and consistent with the underlying types.
+ *
+ * But what if your app has data with massive interfaces such that the TypeScript performance of this
+ * approach becomes a problem? In that case, see {@link Validate}
+ */
+
+/**
+ * A utility that takes two types, K and T, and ensures that K is a valid subset of T.
+ *
+ * That's a mouthful, so let's break it down:
+ *
+ * Let's say you have a User type and an Address type.
+ *
+ * ```ts
+ * interface Address {
+ *   street: string;
+ *   city: string;
+ *   state: string;
+ *   zip: string;
+ * }
+ *
+ * interface User {
+ *   name: string;
+ *   title: string;
+ *   address: Address;
+ * }
+ * ```
+ *
+ * Now, imagine you want to load a preview of the user with some information about their address,
+ * but you don't want to load the entire user or address. You probably want to still ensure
+ * the type of the data you do load matches the underlying Address and User types, but doesn't
+ * include everything.
+ *
+ * You might do something like this:
+ *
+ * ```ts
+ * interface UserPreview {
+ *   name: string;
+ *   address: AddressPreview;
+ * }
+ *
+ * interface AddressPreview {
+ *   city: string;
+ * }
+ * ```
+ *
+ * From a TypeScript performance perspective, this is the best way to approach these preview
+ * types, but this is also error-prone, especially if the User or Address types change.
+ *
+ * Validate can help ensure that your preview types remain valid.
+ *
+ * ```ts
+ * type IsValidUserPreview = Validate<UserPreview, User>; // This will be valid
+ * ```
+ *
+ * For help creating subsets of types, see {@link Mask}
+ */
+
+export { createIncludeValidator };

package/dist/unpkg/dev/types/request.js

@@ -0,0 +1,77 @@
+import { getOrSetUniversal, getOrSetGlobal } from './-private.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+const SkipCache = getOrSetUniversal('SkipCache', Symbol.for('wd:skip-cache'));
+const EnableHydration = getOrSetUniversal('EnableHydration', Symbol.for('wd:enable-hydration'));
+const IS_FUTURE = getOrSetGlobal('IS_FUTURE', Symbol('IS_FUTURE'));
+const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
+
+/**
+ * Use these options to adjust {@link CacheHandler} behavior for a request
+ * via {@link RequestInfo.cacheOptions}.
+ *
+ */
+
+/**
+ * When a {@link Future} resolves, it returns an object
+ * containing the original {@link RequestInfo | request},
+ * the {@link Response | response} set by the handler chain (if any), and
+ * the processed content.
+ */
+
+/**
+ * When a {@link Future} rejects, it throws either an {@link Error}
+ * an {@link AggregateError} or a {@link DOMException} that maintains
+ * the `{ request, response, content }` shape but is also an Error instance
+ * itself.
+ *
+ * If using the error originates from the {@link Fetch | Fetch Handler}
+ * the error will be a {@link FetchError}
+ */
+
+/**
+ * A union of the resolve/reject data types for the {@link Future}
+ * returned by {@link Store.request | request}
+ *
+ * See also the docs for:
+ *
+ * - {@link Future}
+ * - {@link StructuredDataDocument} (resolved/successful requests)
+ * - {@link StructuredErrorDocument} (rejected/failed requests)
+ */
+
+/**
+ * The {@link RequestInit} interface accepted by the native {@link fetch} API.
+ *
+ * WarpDrive provides our own typings due to incompleteness in the native typings.
+ *
+ * @privateRemarks
+ * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+ * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+ * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+ *
+ */
+
+/**
+ * Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional
+ * properties specific to the {@link RequestManager | RequestManager's} capabilities.
+ *
+ * This interface is used to define the shape of a request that can be made via
+ * either the {@link RequestManager.request} or {@link Store.request} methods.
+ *
+ * @privateRemarks
+ * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+ * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+ * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+ *
+ * @public
+ * @since 4.12
+ */
+
+/**
+ * Immutable version of {@link RequestInfo}. This is what is passed to handlers.
+ *
+ */
+
+export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache };

package/dist/unpkg/dev/types/runtime.js

@@ -0,0 +1,34 @@
+import { getOrSetUniversal } from './-private.js';
+const RuntimeConfig = getOrSetUniversal('WarpDriveRuntimeConfig', {
+  debug: {}
+});
+function trySessionStorage() {
+  // This works even when sessionStorage is not available.
+  // See https://github.com/warp-drive-data/warp-drive/issues/9784
+  try {
+    return globalThis.sessionStorage;
+  } catch {
+    return undefined;
+  }
+}
+const storage = trySessionStorage();
+const settings = storage?.getItem('WarpDriveRuntimeConfig');
+if (settings) {
+  Object.assign(RuntimeConfig, JSON.parse(settings));
+}
+function getRuntimeConfig() {
+  return RuntimeConfig;
+}
+
+/**
+ * Upserts the specified logging configuration into the runtime
+ * config.
+ *
+ * globalThis.setWarpDriveLogging({ LOG_CACHE: true } });
+ *
+ */
+function setLogging(config) {
+  Object.assign(RuntimeConfig.debug, config);
+  storage?.setItem('WarpDriveRuntimeConfig', JSON.stringify(RuntimeConfig));
+}
+export { getRuntimeConfig, setLogging };