@warp-drive/core 5.8.0-alpha.4 → 5.8.0-alpha.40

package/dist/types/request.js

@@ -8,19 +8,22 @@ const IS_FUTURE = getOrSetGlobal('IS_FUTURE', Symbol('IS_FUTURE'));
 const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
 
 /**
- * Use these options to adjust CacheHandler behavior for a request.
+ * Use these options to adjust {@link CacheHandler} behavior for a request
+ * via {@link RequestInfo.cacheOptions}.
  *
  */
 
 /**
- * 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}
@@ -28,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)
  */
@@ -69,7 +74,4 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  *
  */
 
-function withBrand(obj) {
-  return obj;
-}
-export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache, withBrand };
+export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache };

package/dist/types/schema/fields.js

@@ -443,6 +443,20 @@
  * @public
  */
 
+/**
+ * A trait for use on a PolarisMode record
+ */
+
+/**
+ * A trait for use on a LegacyMode record
+ */
+
+/**
+ * A union of
+ * - {@link LegacyTrait}
+ * - {@link PolarisTrait}
+ */
+
 /**
  * A no-op type utility that enables type-checking resource schema
  * definitions.

package/dist/types/symbols.js

@@ -11,7 +11,7 @@ const RecordStore = getOrSetGlobal('Store', Symbol('Store'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *
@@ -48,7 +48,7 @@ const Type = getOrSetGlobal('$type', Symbol('$type'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *

package/dist/unpkg/dev/-private-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/unpkg/dev/build-config/babel-macros.js

@@ -0,0 +1 @@
+export { macros } from '@warp-drive/build-config/babel-macros';

package/dist/unpkg/dev/build-config/canary-features.js

@@ -0,0 +1 @@
+export * from '@warp-drive/build-config/canary-features';

package/dist/unpkg/dev/build-config/debugging.js

@@ -0,0 +1 @@
+export * from '@warp-drive/build-config/debugging';

package/dist/unpkg/dev/build-config/deprecations.js

@@ -0,0 +1 @@
+export * from '@warp-drive/build-config/deprecations';

package/dist/unpkg/dev/build-config/env.js

@@ -0,0 +1 @@
+export { DEBUG, IS_CI, IS_RECORDING, PRODUCTION, SHOULD_RECORD, TESTING } from '@warp-drive/build-config/env';

package/dist/unpkg/dev/build-config/macros.js

@@ -0,0 +1 @@
+export { assert } from '@warp-drive/build-config/macros';

package/dist/unpkg/dev/build-config.js

@@ -0,0 +1 @@
+export { babelPlugin, setConfig } from '@warp-drive/build-config';

package/dist/unpkg/dev/configure-BC66sfNO.js

@@ -0,0 +1,183 @@
+import { getOrSetGlobal, peekTransient, setTransient } from './types/-private.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+const ARRAY_SIGNAL = getOrSetGlobal('#[]', Symbol('#[]'));
+const OBJECT_SIGNAL = getOrSetGlobal('#{}', Symbol('#{}'));
+
+/**
+ * Requirements:
+ *
+ * Signal:
+ *
+ * - signal: a way of creating a reference that we can dirty when we desire to notify
+ *         - @signal: a way of creating an accessor on an object that subscribes to a signal on access
+ *                    and notifies the signal on set, or of upgrading a descriptor to be such an accessor
+ *         - defineSignal: a way of creating a signal on an object
+ *         - notifySignal: a way of notifying the underlying signal that it has been dirtied
+ *         - peekSignal: a way of inspecting the signal without notifying it
+ *
+ *  - gate: a memoized getter function that re-runs when on access if its signal is dirty
+ *          conceptually, a gate is a tightly coupled signal and memo
+ *         - @gate: a way of creating a gate on an object or upgrading a descriptor with a getter
+ *                  to be a gate
+ *         - defineGate: a way of creating a gate on an object
+ *         - notifySignal: a way of notifying the signal for a gate that it has been dirtied
+ *
+ * - memo:
+ *        - @memo: a way of creating a memoized getter on an object or upgrading a descriptor with a getter
+ *                 to be a memo
+ *        - defineMemo: a way of creating a memo on an object
+ *
+ * - signalStore: storage bucket for signals associated to an object
+ *        - withSignalStore: a way of pre-creating a signal store on an object
+ *
+ *
+ * @internal
+ */
+
+/**
+ * An Opaque type that represents a framework specific or TC39 signal.
+ *
+ * It may be an array of signals or a single signal.
+ *
+ * @private
+ */
+
+/**
+ * The hooks which MUST be configured in order to use reactive arrays,
+ * resources and documents with framework specfic signals or TC39 signals.
+ *
+ * Support for multiple frameworks simultaneously can be done via
+ * this abstraction by returning multiple signals from the `createSignal`
+ * method, and consuming the correct one via the correct framework via
+ * the `consumeSignal` and `notifySignal` methods.
+ *
+ * Unlike many signals implementations, WarpDrive does not wrap values as
+ * signals directly, but instead uses signals to alert the reactive layer
+ * to changes in the underlying cache. E.g. a signal is associated to a value,
+ * but does not serve as the cache for that value directly. We refer to this as
+ * a "gate", the pattern has also been called "side-signals".
+ *
+ * A no-op implementation is allowed, though it may lead to performance issues
+ * in locations that use createMemo as no memoization would be done. This is
+ * typically desirable only when integrating with a framework that does its own
+ * memoization and does not integrate with any signals-like primitive. For these
+ * scenarios you may also be interested in integrating with the {@link NotificationManager}
+ * more directly.
+ *
+ * @public
+ */
+
+/**
+ * Contains information a {@link SignalHooks} implementation may want
+ * to use, such as the specialized key used for the signal
+ * representing an array's contents / length.
+ *
+ * ```ts
+ * interface HooksOptions {
+ *   wellknown: {
+ *     Array: symbol | string;
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+
+/**
+ * Configures the signals implementation to use. Supports multiple
+ * implementations simultaneously.
+ *
+ * See {@link HooksOptions} for the options passed to the provided function
+ * when called.
+ *
+ * See {@link SignalHooks} for the implementation the callback function should
+ * return.
+ *
+ * @public
+ * @param buildConfig - a function that takes options and returns a configuration object
+ */
+function setupSignals(buildConfig) {
+  // We want to assert this but can't because too many package manager
+  // and bundler bugs exist that cause this to be called multiple times
+  // for what should be a single call.
+  // assert(`Cannot override configured signal hooks`, peekTransient('signalHooks') === null);
+  const hooks = buildConfig({
+    wellknown: {
+      Array: ARRAY_SIGNAL
+    }
+  });
+  setTransient('signalHooks', hooks);
+}
+
+/**
+ * Internal method for consuming the configured `createSignal` hook
+ *
+ * @private
+ */
+function createSignal(obj, key) {
+  const signalHooks = peekTransient('signalHooks');
+  (test => {
+    if (!test) {
+      throw new Error(`Signal hooks not configured`);
+    }
+  })(signalHooks);
+  return signalHooks.createSignal(obj, key);
+}
+
+/**
+ * Internal method for consuming the configured `consumeSignal` hook
+ *
+ * @private
+ */
+function consumeSignal(signal) {
+  const signalHooks = peekTransient('signalHooks');
+  (test => {
+    if (!test) {
+      throw new Error(`Signal hooks not configured`);
+    }
+  })(signalHooks);
+  return signalHooks.consumeSignal(signal);
+}
+
+/**
+ * Internal method for consuming the configured `notifySignal` hook
+ *
+ * @private
+ */
+function notifySignal(signal) {
+  const signalHooks = peekTransient('signalHooks');
+  (test => {
+    if (!test) {
+      throw new Error(`Signal hooks not configured`);
+    }
+  })(signalHooks);
+  return signalHooks.notifySignal(signal);
+}
+function createMemo(object, key, fn) {
+  const signalHooks = peekTransient('signalHooks');
+  (test => {
+    if (!test) {
+      throw new Error(`Signal hooks not configured`);
+    }
+  })(signalHooks);
+  return signalHooks.createMemo(object, key, fn);
+}
+function willSyncFlushWatchers() {
+  const signalHooks = peekTransient('signalHooks');
+  (test => {
+    if (!test) {
+      throw new Error(`Signal hooks not configured`);
+    }
+  })(signalHooks);
+  return signalHooks.willSyncFlushWatchers();
+}
+function waitFor(promise) {
+  const signalHooks = peekTransient('signalHooks');
+  if (signalHooks?.waitFor) {
+    return signalHooks.waitFor(promise);
+  }
+  return promise;
+}
+export { ARRAY_SIGNAL as A, OBJECT_SIGNAL as O, consumeSignal as a, createMemo as b, createSignal as c, willSyncFlushWatchers as d, notifySignal as n, setupSignals as s, waitFor as w };

package/dist/unpkg/dev/configure.js

@@ -0,0 +1 @@
+export { s as setupSignals } from "./configure-BC66sfNO.js";