@warp-drive/core 5.8.0-alpha.3 → 5.8.0-alpha.32

package/dist/unpkg/dev/declarations/store/-private/new-core-tmp/reactivity/configure.d.ts

@@ -0,0 +1,138 @@
+export declare const ARRAY_SIGNAL: "___(unique) Symbol(#[])";
+export declare const OBJECT_SIGNAL: "___(unique) Symbol(#{})";
+/**
+* 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
+*/
+export interface SignalHooks<T = SignalRef> {
+	/**
+	* Create a signal for the given key associated to the given object.
+	*
+	* This method does *not* need to cache the signal, it will only be
+	* called once for a given object and key. However, if your framework
+	* will look for a signal cache on the object in a given location or may
+	* have created its own signal on the object for some reason it may be
+	* useful to ensure such cache is properly updated.
+	*/
+	createSignal: (obj: object, key: string | symbol) => T;
+	/**
+	* Consume (mark as acccessed) a signal previously created via createSignal.
+	*/
+	consumeSignal: (signal: T) => void;
+	/**
+	* Alert a signal previously created via createSignal that its associated value has changed.
+	*/
+	notifySignal: (signal: T) => void;
+	/**
+	* Take the given function and wrap it in signals-based memoization. Analagous
+	* to a Computed in the TC39 spec.
+	*
+	* Should return a function which when run provides the latest value of the original
+	* function.
+	*/
+	createMemo: <F>(obj: object, key: string | symbol, fn: () => F) => () => F;
+	/**
+	* If the signals implementation allows synchronous flushing of watchers, and
+	* has scheduled such a flush (e.g. watchers will run before the current calling
+	* context yields) this should return "true".
+	*
+	* This is generally something that should return false for anything but the few
+	* frameworks that extensively handle their own reactivity => render scheduling.
+	*
+	* For an example, see EmberJS's backburner scheduler which functioned as a microtask
+	* polyfill.
+	*/
+	willSyncFlushWatchers: () => boolean;
+	/**
+	* An optional method that allows wrapping key promises within WarpDrive
+	* for things like test-waiters.
+	*/
+	waitFor?: <K>(promise: Promise<K>) => Promise<K>;
+}
+/**
+* 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
+*/
+export interface HooksOptions {
+	/**
+	* A list of specialized symbols/strings
+	* used by WarpDrive to encapsulate key
+	* reactivity concerns.
+	*/
+	wellknown: {
+		/**
+		* The key used when the signal provides reactivity for the
+		* `length` or "contents" of an array.
+		*
+		* Arrays only use a single signal for all accesses, regardless
+		* of index, property or method: this one.
+		*/
+		Array: symbol | string;
+	};
+}
+/**
+* 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
+*/
+export declare function setupSignals<T>(buildConfig: (options: HooksOptions) => SignalHooks<T>): void;
+/**
+* Internal method for consuming the configured `createSignal` hook
+*
+* @private
+*/
+export declare function createSignal(obj: object, key: string | symbol): SignalRef;
+/**
+* Internal method for consuming the configured `consumeSignal` hook
+*
+* @private
+*/
+export declare function consumeSignal(signal: SignalRef): void;
+/**
+* Internal method for consuming the configured `notifySignal` hook
+*
+* @private
+*/
+export declare function notifySignal(signal: SignalRef): void;
+export declare function createMemo<T>(object: object, key: string | symbol, fn: () => T): () => T;
+export declare function willSyncFlushWatchers(): boolean;
+export declare function waitFor<K>(promise: Promise<K>): Promise<K>;

package/dist/unpkg/dev/declarations/store/-private/new-core-tmp/reactivity/internal.d.ts

@@ -0,0 +1,154 @@
+import { ARRAY_SIGNAL, OBJECT_SIGNAL, type SignalRef } from "./configure.js";
+export type { SignalRef };
+export { ARRAY_SIGNAL, OBJECT_SIGNAL };
+interface Initializer {
+	value: () => unknown;
+}
+export declare function makeInitializer(fn: () => unknown): Initializer;
+/**
+* A WarpDriveSignal is a wrapper around a framework specific or TC39 signal
+* that enables us to store and manage the signal in a universal way.
+*
+* WarpDrive uses signals to manage three separate concepts:
+*
+* - as a `storage` for a value local to the object that we want to be reactive
+*   (see `@local` schema field for an example)
+* - as a `gate` for a memoized getter that we want to act as a reactive property
+*   but whose value is computed/pulled from a non-reactive source elsewhere
+*   and whose latest value is stored in the signal
+*   (see `field` schema field for an example)
+* - as a `gate` with a manually managed value updated on pull when `isStale` is true
+*
+*
+* It offers
+*
+* - a non-reactive way to access/update the current value
+* - a non-reactive way to mark the signal as dirtied
+* - a non-reactive way to store content for why the signal was dirtied
+* - access to the underlying Signal(s) in-use
+*
+* For debugging:
+* - the "key" or "name" of the signal
+* - the "object identity" or "context" to which the signal is attached
+*
+* @private
+*/
+export interface WarpDriveSignal {
+	/**
+	* The underlying signal(s) in-use.
+	*
+	* Generally, this is a single signal.
+	*
+	* In some cases multiple signals need to be condensed,
+	* such as to support legacy Ember Array APIs or to
+	* support reactive-objects shared between the code of
+	* multiple frameworks.
+	*
+	* In such cases, this value may be an array.
+	*
+	* e.g. (pseudo-code for Ember):
+	*
+	* setupSignals({
+	*   createSignal: (obj, key, initialValue) => {
+	*     if (isArraySignal(key)) {
+	*       return [
+	*         tagForProperty(obj, key),
+	*         tagForProperty(obj, '[]'),
+	*         tagForProperty(obj, 'length'),
+	*       ];
+	*     }
+	*     return tagForProperty(obj, key);
+	*   },
+	*
+	*   consumeSignal: (signal) => {
+	*     if (Array.isArray(signal)) {
+	*       signal.forEach((s) => consumeTag(s));
+	*     } else {
+	*       consumeTag(signal);
+	*     }
+	*   },
+	*
+	*   dirtySignal: (signal) => {
+	*     if (Array.isArray(signal)) {
+	*       signal.forEach((s) => dirtyTag(s));
+	*     } else {
+	*       dirtyTag(signal);
+	*     }
+	*   },
+	* });
+	*
+	* @private
+	*/
+	signal: SignalRef;
+	/**
+	* The last "value" computed for this signal when
+	* a signal is also used for storage.
+	*
+	* @private
+	*/
+	value: unknown;
+	/**
+	* Whether ths signal is known to have been dirtied.
+	* This is useful *both* when manually managing the
+	* `value` cache and when using the signal as a
+	* "gate"
+	*
+	* @private
+	*/
+	isStale: boolean;
+}
+/**
+* We attach signals to their context object via
+* a Map attached to the object via this symbol.
+*
+* This allows us to store multiple signals
+* on the same object with smaller memory
+* overhead and no WeakMap lookups.
+*
+* Performance sensitive objects should
+* pre-warm their shape by assigning this
+* during initialization.
+*
+* ```ts
+* initializeSignalStore(obj);
+* ```
+*
+* @private
+*/
+export declare const Signals: "___(unique) Symbol(Signals)";
+export type SignalStore = Map<string | symbol, WarpDriveSignal>;
+/**
+* A type util to recast the object as having a signal store.
+*
+* @private
+*/
+export declare function upgradeWithSignals<T extends object>(obj: T): asserts obj is T & {
+	[Signals]: SignalStore;
+};
+/**
+* A util that will create a signal store on the object
+* if it does not already exist and returns the associated
+* signal store.
+*
+* @private
+*/
+export declare function withSignalStore<T extends object>(obj: T): SignalStore;
+/**
+* A util that will create a signal store on the object
+* if it does not already exist.
+*
+* Useful for pre-warming the shape of an object to ensure
+* a key-transition to add it is not required later.
+*
+* @private
+*/
+export declare function initializeSignalStore<T extends object>(obj: T): asserts obj is T & {
+	[Signals]: SignalStore;
+};
+export declare function createInternalSignal(signals: SignalStore, obj: object, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function getOrCreateInternalSignal(signals: SignalStore, obj: object, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function createInternalMemo<T>(signals: SignalStore, object: object, key: string | symbol, fn: () => T): () => T;
+export declare function consumeInternalMemo<T>(fn: () => T): T;
+export declare function peekInternalSignal(signals: SignalStore | undefined, key: string | symbol): WarpDriveSignal | undefined;
+export declare function consumeInternalSignal(signal: WarpDriveSignal): void;
+export declare function notifyInternalSignal(signal: WarpDriveSignal | undefined): void;

package/dist/unpkg/dev/declarations/store/-private/new-core-tmp/reactivity/signal.d.ts

@@ -0,0 +1,56 @@
+import type { SignalStore, WarpDriveSignal } from "./internal.js";
+/**
+* Creates a signal for the key/object pairing and subscribes to the signal.
+*
+* Use when you need to ensure a signal exists and is subscribed to.
+*
+* @private
+*/
+export declare function entangleSignal<T extends object>(signals: SignalStore, obj: T, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function entangleInitiallyStaleSignal<T extends object>(signals: SignalStore, obj: T, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function createSignalDescriptor(key: string | symbol, intialValue: unknown): PropertyDescriptor;
+/**
+* define an enumerable signal property.
+*
+* Akin to Object.defineProperty.
+*
+* The signal will be lazily created when accessed and scoped to the
+* instance of the object.
+*
+* @private
+*/
+export declare function defineSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+/**
+* Define a non-enumerable signal property.
+*
+* @private
+*/
+export declare function defineNonEnumerableSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+interface DecoratorPropertyDescriptor extends PropertyDescriptor {
+	initializer?: () => unknown;
+}
+/**
+* Decorator version of creating a signal.
+*/
+export declare function signal<
+	T extends object,
+	K extends keyof T & string
+>(target: T, key: K, descriptor?: DecoratorPropertyDescriptor): void;
+/**
+* Decorator version of creating a memoized getter
+*/
+export declare function memoized<
+	T extends object,
+	K extends keyof T & string
+>(target: T, key: K, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+* Decorator version of creating a gate.
+*
+* @private
+*/
+export declare function gate<
+	T extends object,
+	K extends keyof T & string
+>(_target: T, key: K, desc: PropertyDescriptor): PropertyDescriptor;
+export declare function defineGate<T extends object>(obj: T, key: string, desc: PropertyDescriptor): void;
+export {};