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

package/dist/index.js

@@ -1,8 +1,8 @@
-export { C as CacheHandler, V as Fetch, W as RequestManager, S as Store, r as recordIdentifierFor, $ as setIdentifierForgetMethod, Y as setIdentifierGenerationMethod, a0 as setIdentifierResetMethod, Z as setIdentifierUpdateMethod, a1 as setKeyInfoForResource, s as storeFor, X as useRecommendedStore } from "./index-B1cSRj-N.js";
-import "./symbols-sql1_mdx.js";
-import '@ember/debug';
+export { C as CacheHandler, F as Fetch, z as RequestManager, S as Store, r as cacheKeyFor, r as recordIdentifierFor, E as setIdentifierForgetMethod, B as setIdentifierGenerationMethod, G as setIdentifierResetMethod, D as setIdentifierUpdateMethod, H as setKeyInfoForResource, s as storeFor, A as useRecommendedStore } from "./index-CQP2NSqg.js";
+import "./symbols-3C1OkYtZ.js";
+import "./configure-DPUFCemT.js";
 import '@embroider/macros';
-import './utils/string.js';
-import "./configure-C3x8YXzL.js";
 import "./default-cache-policy-D7_u4YRH.js";
+import '@ember/debug';
+import './utils/string.js';
 import './types/runtime.js';

package/dist/reactive/-private.js

@@ -1 +1 @@
-export { C as Context } from "../symbols-sql1_mdx.js";
+export { a as Context } from "../symbols-3C1OkYtZ.js";

package/dist/reactive.js

@@ -1,129 +1,4 @@
-export { O as SchemaService, L as checkout, U as commit, q as createRequestSubscription, Q as fromIdentity, p as getPromiseState, t as getRequestState, M as instantiateRecord, T as registerDerivations, N as teardownRecord, P as withDefaults } from "./index-B1cSRj-N.js";
-export { a as Checkout } from "./symbols-sql1_mdx.js";
-import './types/request.js';
-import '@embroider/macros';
-import '@ember/debug';
-import './utils/string.js';
-import "./configure-C3x8YXzL.js";
-const Subscriptions = new WeakMap();
-
-/**
- * `ExpensiveSubscription` is a mechanism for non-reactive
- * frameworks such as `react` to integrate with WarpDrive.
- *
- * This mechanism should never be used by frameworks or libraries
- * that support fine-grained reactivity.
- *
- * ExpensiveSubscription is expensive *because* it doubles the number
- * of notification callbacks required for each resource contained in
- * the request being subscribed to. The more requests in-use, the more
- * this cost adds up.
- */
-class ExpensiveSubscription {
-  constructor(store, request) {
-    this._store = store;
-    this._request = request;
-    this._callbacks = new Set();
-    this._resources = new Map();
-    this._subscription = store.notifications.subscribe(request, this._notifyRequestChange);
-    this._updateResourceCallbacks();
-  }
-  _updateResourceCallbacks() {
-    const request = this._request;
-    const store = this._store;
-    const {
-      notifications
-    } = store;
-    const req = store.cache.peek(request);
-    const resources = this._resources;
-    const isInitialSubscription = resources.size === 0;
-    if (req && 'data' in req) {
-      if (Array.isArray(req.data)) {
-        for (const resourceKey of req.data) {
-          if (isInitialSubscription || !resources.has(resourceKey)) {
-            resources.set(resourceKey, notifications.subscribe(resourceKey, this._scheduleNotify));
-          }
-        }
-      } else if (req.data) {
-        if (isInitialSubscription || !resources.has(req.data)) {
-          resources.set(req.data, notifications.subscribe(req.data, this._scheduleNotify));
-        }
-      }
-    }
-    if (req && 'included' in req && Array.isArray(req.included)) {
-      for (const resourceKey of req.included) {
-        if (isInitialSubscription || !resources.has(resourceKey)) {
-          resources.set(resourceKey, notifications.subscribe(resourceKey, this._scheduleNotify));
-        }
-      }
-    }
-  }
-  _notifyRequestChange = () => {
-    this._updateResourceCallbacks();
-    this._scheduleNotify();
-  };
-  _scheduleNotify = () => {
-    this._notify = this._notify || Promise.resolve().then(() => {
-      for (const callback of this._callbacks) {
-        callback();
-      }
-      this._notify = null;
-    });
-  };
-  addWatcher(callback) {
-    this._callbacks.add(callback);
-  }
-  removeWatcher(callback) {
-    this._callbacks.delete(callback);
-    if (this._callbacks.size === 0) {
-      this.destroy();
-    }
-  }
-  destroy() {
-    Subscriptions.delete(this._request);
-    const {
-      notifications
-    } = this._store;
-    if (this._subscription) {
-      notifications.unsubscribe(this._subscription);
-    }
-    for (const token of this._resources.values()) {
-      notifications.unsubscribe(token);
-    }
-    this._callbacks.clear();
-    this._resources.clear();
-  }
-}
-
-/**
- * Creates an {@link ExpensiveSubscription} for the {@link RequestKey}
- * if one does not already exist and adds a watcher to it.
- *
- * Returns a cleanup function. This should be called on-mount by a component
- * that wants to subscribe to a request and cleanup should be called on dismount.
- *
- * ::: warning ⚠️ Avoid Using If Your App Supports Fine-grained Reactivity
- * This mechanism should never be used by frameworks or libraries
- * that support fine-grained reactivity.
- * :::
- *
- * `ExpensiveSubscription` is a mechanism for non-reactive
- * frameworks such as `react` to integrate with WarpDrive, for instance
- * by treating a request as an [external store](https://react.dev/reference/react/useSyncExternalStore)
- *
- * `ExpensiveSubscription` is expensive *because* it doubles the number
- * of notification callbacks required for each resource contained in
- * the request being subscribed to. The more requests in-use, the more
- * this cost adds up.
- */
-function getExpensiveRequestSubscription(store, requestKey, callback) {
-  let subscription = Subscriptions.get(requestKey);
-  if (!subscription) {
-    subscription = new ExpensiveSubscription(store, requestKey);
-  }
-  subscription.addWatcher(callback);
-  return () => {
-    subscription.removeWatcher(callback);
-  };
-}
-export { getExpensiveRequestSubscription };
+export { u as SchemaService, p as checkout, y as commit, v as fromIdentity, q as instantiateRecord, x as registerDerivations, t as teardownRecord, w as withDefaults } from "./index-CQP2NSqg.js";
+export { C as Checkout } from "./symbols-3C1OkYtZ.js";
+export { f as createRequestSubscription, i as getPromiseState, h as getRequestState } from "./configure-DPUFCemT.js";
+import '@embroider/macros';

package/dist/request.js

@@ -1 +1,49 @@
-export { i as createDeferred, g as getPromiseResult, s as setPromiseResult, w as withBrand, h as withReactiveResponse, f as withResponseType } from "./request-oqoLC9rz.js";
+export { c as createDeferred, g as getPromiseResult, s as setPromiseResult } from "./future-BKkJJkj7.js";
+
+/**
+ * Brands the supplied object with the supplied response type.
+ *
+ * ```ts
+ * import type { ReactiveDataDocument } from '@warp-drive/core/reactive';
+ * import { withResponseType } from '@warp-drive/core/request';
+ * import type { User } from '#/data/user.ts'
+ *
+ * const result = await store.request(
+ *  withResponseType<ReactiveDataDocument<User>>({ url: '/users/1' })
+ * );
+ *
+ * result.content.data; // will have type User
+ * ```
+ *
+ */
+function withResponseType(obj) {
+  return obj;
+}
+
+/**
+ * Brands the supplied object with the supplied response type
+ * wrapped in {@link ReactiveDataDocument}. This is a convenience for
+ * the common case of using {@link withResponseType} with `ReactiveDataDocument`.
+ *
+ * ```ts
+ * import { withReactiveResponse } from '@warp-drive/core/request';
+ * import type { User } from '#/data/user.ts'
+ *
+ * const result = await store.request(
+ *   withReactiveResponse<User>({ url: '/users/1' })
+ * );
+ *
+ * result.content.data; // will have type User
+ * ```
+ *
+ * @public
+ */
+function withReactiveResponse(obj) {
+  return obj;
+}
+
+/**
+ * @deprecated use {@link withResponseType} instead
+ */
+const withBrand = withResponseType;
+export { withBrand, withReactiveResponse, withResponseType };

package/dist/signals/-leaked.js

@@ -0,0 +1 @@
+export { D as DISPOSE, a as defineGate, d as defineNonEnumerableSignal, b as defineSignal, e as entangleSignal, g as gate, m as memoized, n as notifyInternalSignal, p as peekInternalSignal, s as signal, w as waitFor, c as withSignalStore } from "../configure-DPUFCemT.js";

package/dist/store/-private.js

@@ -1,2 +1 @@
-export { C as CacheHandler, D as DISPOSE, R as RecordArrayManager, E as Signals, S as Store, k as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, h as assertPrivateCapabilities, d as assertPrivateStore, b as coerceId, c as constructResource, J as consumeInternalSignal, G as createInternalMemo, l as createLegacyManyArray, q as createRequestSubscription, A as defineGate, B as defineNonEnumerableSignal, z as defineSignal, e as ensureStringId, y as entangleInitiallyStaleSignal, x as entangleSignal, f as fastPush, w as gate, K as getOrCreateInternalSignal, p as getPromiseState, t as getRequestState, g as isPrivateStore, a as isRequestKey, i as isResourceKey, m as log, o as logGroup, v as memoized, I as notifyInternalSignal, F as peekInternalSignal, r as recordIdentifierFor, j as setRecordIdentifier, u as signal, s as storeFor, H as withSignalStore } from "../index-B1cSRj-N.js";
-export { A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, w as waitFor } from "../configure-C3x8YXzL.js";
+export { C as CacheHandler, R as RecordArrayManager, S as Store, k as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, h as assertPrivateCapabilities, d as assertPrivateStore, b as coerceId, c as constructResource, l as createLegacyManyArray, e as ensureStringId, f as fastPush, g as isPrivateStore, a as isRequestKey, i as isResourceKey, m as log, o as logGroup, r as recordIdentifierFor, j as setRecordIdentifier, s as storeFor } from "../index-CQP2NSqg.js";

package/dist/symbols-3C1OkYtZ.js

@@ -0,0 +1,39 @@
+import { getOrSetGlobal } from './types/-private.js';
+
+///////////////////
+///// WARNING /////
+///////////////////
+
+// Great, got your attention with that warning didn't we?
+// Good. Here's the deal: typescript treats symbols as unique types.
+// If by accident a module creating a symbol is processed more than
+// once, the symbol will be different in each processing. This will
+// cause a type error.
+// It could also cause a runtime error if the symbol is used innapropriately.
+// However, this case is extremely hard to hit and would require other things
+// to go wrong first.
+//
+// So, why do the warning? And why do we lie about the types of the symbols?
+//
+// Because we intentionally create multiple copies of them within the types
+// at build time. This is because we rollup our d.ts files in order to give
+// our consumers a better experience.
+//
+// However, no tool today supports rolling up d.ts files with multiple entry
+// points correctly. The tool we use currently (vite-plugin-dts) uses @microsoft/api-extractor
+// which creates a fully unique stand-alone types file per-entry-point. Thus
+// every entry point that uses one of these symbols somewhere will have accidentally
+// created a new symbol type.
+//
+// This cast allows us to rollup these types using this tool while not encountering
+// the unique symbol type issue.
+//
+// Note that none of these symbols are part of the public API, these are used for
+// debugging DX and as a safe way to provide an intimate contract on public objects.
+
+const SOURCE = getOrSetGlobal('SOURCE', Symbol('#source'));
+const Destroy = getOrSetGlobal('Destroy', Symbol.dispose || Symbol.for('Dispose'));
+const Checkout = getOrSetGlobal('Checkout', Symbol('Checkout'));
+const Commit = getOrSetGlobal('Commit', Symbol('Commit'));
+const Context = getOrSetGlobal('Context', Symbol('Context'));
+export { Checkout as C, Destroy as D, SOURCE as S, Context as a, Commit as b };

package/dist/types/-private.js

@@ -1,6 +1,6 @@
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const name = "@warp-drive/core";
-const version = "5.8.0-alpha.9";
+const version = "5.8.0-beta.1";
 
 // in testing mode, we utilize globals to ensure only one copy exists of
 // these maps, due to bugs in ember-auto-import

package/dist/types/record.js

@@ -61,4 +61,131 @@ function createIncludeValidator() {
     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/types/request.js

@@ -14,14 +14,16 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  */
 
 /**
- * When a handler chain resolves, it returns an object
- * containing the original request, the response set by the handler
- * chain (if any), and the processed content.
+ * 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 handler chain rejects, it throws an Error that maintains the
- * `{ request, response, content }` shape but is also an Error instance
+ * 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}
@@ -29,10 +31,12 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  */
 
 /**
- * A union of the resolve/reject data types for a request.
+ * A union of the resolve/reject data types for the {@link Future}
+ * returned by {@link Store.request | request}
  *
- * See the docs for:
+ * See also the docs for:
  *
+ * - {@link Future}
  * - {@link StructuredDataDocument} (resolved/successful requests)
  * - {@link StructuredErrorDocument} (rejected/failed requests)
  */