@warp-drive/core 5.9.0-beta.0 → 5.9.0-beta.2

package/declarations/signals/reactivity/configure.d.ts

@@ -1,138 +0,0 @@
-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/declarations/signals/reactivity/internal.d.ts

@@ -1,154 +0,0 @@
-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/declarations/signals/reactivity/signal.d.ts

@@ -1,56 +0,0 @@
-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 {};