@ember-data/tracking 5.4.0-alpha.30 → 5.4.0-alpha.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ember-data/tracking",
   "description": "Tracking Primitives for controlling change notification of Tracked properties when working with EmberData",
-  "version": "5.4.0-alpha.30",
+  "version": "5.4.0-alpha.31",
   "private": false,
   "license": "MIT",
   "author": "Chris Thoburn <runspired@users.noreply.github.com>",
@@ -27,13 +27,14 @@
     }
   },
   "dependencies": {
-    "@ember-data/private-build-infra": "5.4.0-alpha.30",
+    "@ember-data/private-build-infra": "5.4.0-alpha.31",
     "@embroider/macros": "^1.13.5",
     "ember-cached-decorator-polyfill": "^1.0.2",
     "ember-cli-babel": "^8.2.0",
     "pnpm-sync-dependencies-meta-injected": "0.0.10"
   },
   "files": [
+    "unstable-preview-types",
     "addon-main.cjs",
     "addon",
     "README.md",
@@ -62,7 +63,7 @@
     "@glimmer/validator": "^0.88.1",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@warp-drive/internal-config": "5.4.0-alpha.30",
+    "@warp-drive/internal-config": "5.4.0-alpha.31",
     "ember-source": "~5.6.0",
     "rollup": "^4.9.6",
     "typescript": "^5.3.3",
@@ -74,7 +75,7 @@
   "scripts": {
     "lint": "eslint . --quiet --cache --cache-strategy=content --ext .js,.ts,.mjs,.cjs --report-unused-disable-directives",
     "build:runtime": "rollup --config && babel ./addon --out-dir addon --plugins=../private-build-infra/src/transforms/babel-plugin-transform-ext.js",
-    "build:types": "echo \"Types are private\" && exit 0",
+    "build:types": "tsc --build",
     "_build": "bun run build:runtime && bun run build:types",
     "_syncPnpm": "bun run sync-dependencies-meta-injected"
   }

package/unstable-preview-types/-private.d.ts

@@ -0,0 +1,186 @@
+/// <reference types="ember-source/types" />
+/// <reference types="ember-source/types" />
+import { tagForProperty } from '@ember/-internals/metal';
+/**
+ * This package provides primitives that allow powerful low-level
+ * adjustments to change tracking notification behaviors.
+ *
+ * Typically you want to use these primitives when you want to divorce
+ * property accesses on EmberData provided objects from the current
+ * tracking context. Typically this sort of thing occurs when serializing
+ * tracked data to send in a request: the data itself is often ancillary
+ * to the thing which triggered the request in the first place and you
+ * would not want to re-trigger the request for any update to the data.
+ *
+ * @module @ember-data/tracking
+ * @main @ember-data/tracking
+ */
+type OpaqueFn = (...args: unknown[]) => unknown;
+type Tag = {
+    ref: null;
+    t: boolean;
+};
+/**
+ * If there is a current transaction, ensures that the relevant tag (and any
+ * array computed chains symbols, if applicable) will be consumed during the
+ * transaction.
+ *
+ * If there is no current transaction, will consume the tag(s) immediately.
+ *
+ * @internal
+ * @param obj
+ */
+export declare function subscribe(obj: Tag | Signal): void;
+export declare function addToTransaction(obj: Tag | Signal): void;
+export declare function addTransactionCB(method: OpaqueFn): void;
+/**
+ * Run `method` without subscribing to any tracked properties
+ * controlled by EmberData.
+ *
+ * This should rarely be used except by libraries that really
+ * know what they are doing. It is most useful for wrapping
+ * certain kinds of fetch/query logic from within a `Resource`
+ * `hook` or other similar pattern.
+ *
+ * @function untracked
+ * @public
+ * @static
+ * @for @ember-data/tracking
+ * @param method
+ * @return result of invoking method
+ */
+export declare function untracked<T extends OpaqueFn>(method: T): ReturnType<T>;
+/**
+ * Run the method, subscribing to any tracked properties
+ * managed by EmberData that were accessed or written during
+ * the method's execution as per-normal but while allowing
+ * interleaving of reads and writes.
+ *
+ * This is useful when for instance you want to perform
+ * a mutation based on existing state that must be read first.
+ *
+ * @function transact
+ * @public
+ * @static
+ * @for @ember-data/tracking
+ * @param method
+ * @return result of invoking method
+ */
+export declare function transact<T extends OpaqueFn>(method: T): ReturnType<T>;
+/**
+ * A helpful utility for creating a new function that
+ * always runs in a transaction. E.G. this "memoizes"
+ * calling `transact(fn)`, currying args as necessary.
+ *
+ * @method memoTransact
+ * @public
+ * @static
+ * @for @ember-data/tracking
+ * @param method
+ * @return a function that will invoke method in a transaction with any provided args and return its result
+ */
+export declare function memoTransact<T extends OpaqueFn>(method: T): (...args: unknown[]) => ReturnType<T>;
+export declare const Signals: unique symbol;
+/**
+ *  use to add a signal property to the prototype of something.
+ *
+ *  First arg is the thing to define on
+ *  Second arg is the property name
+ *  Third agg is the initial value of the property if any.
+ *
+ *  for instance
+ *
+ *  ```ts
+ *  class Model {}
+ *  defineSignal(Model.prototype, 'isLoading', false);
+ *  ```
+ *
+ *  This is sort of like using a stage-3 decorator but works today
+ *  while we are still on legacy decorators.
+ *
+ *  e.g. it is equivalent to
+ *
+ *  ```ts
+ *  class Model {
+ *    @signal accessor isLoading = false;
+ *  }
+ *  ```
+ *
+ *  @internal
+ */
+export declare function defineSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+export interface Signal {
+    /**
+     * Key on the associated object
+     * @internal
+     */
+    key: string;
+    _debug_base?: string;
+    /**
+     * Whether this signal is part of an active transaction.
+     * @internal
+     */
+    t: boolean;
+    /**
+     * Whether to "bust" the lastValue cache
+     * @internal
+     */
+    shouldReset: boolean;
+    /**
+     * The framework specific "signal" e.g. glimmer "tracked"
+     * or starbeam "cell" to consume/invalidate when appropriate.
+     *
+     * @internal
+     */
+    tag: ReturnType<typeof tagForProperty>;
+    /**
+     * In classic ember, arrays must entangle a `[]` symbol
+     * in addition to any other tag in order for array chains to work.
+     *
+     * Note, this symbol MUST be the one that ember itself generates
+     *
+     * @internal
+     */
+    '[]': ReturnType<typeof tagForProperty> | null;
+    /**
+     * In classic ember, arrays must entangle a `@length` symbol
+     * in addition to any other tag in order for array chains to work.
+     *
+     * Note, this symbol MUST be the one that ember itself generates
+     *
+     * @internal
+     */
+    '@length': ReturnType<typeof tagForProperty> | null;
+    /**
+     * The lastValue computed for this signal when
+     * a signal is also used for storage.
+     * @internal
+     */
+    lastValue: unknown;
+}
+export declare function createArrayTags<T extends object>(obj: T, signal: Signal): void;
+/**
+ * Create a signal for the key/object pairing.
+ *
+ * @internal
+ * @param obj Object we're creating the signal on
+ * @param key Key to create the signal for
+ * @return the signal
+ */
+export declare function createSignal<T extends object>(obj: T, key: string): Signal;
+/**
+ * Create 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.
+ *
+ * @internal
+ * @param signals Map of signals
+ * @param obj Object we're creating the signal on
+ * @param key Key to create the signal for
+ * @return the signal
+ */
+export declare function entangleSignal<T extends object>(signals: Map<string, Signal>, obj: T, key: string): Signal;
+export declare function getSignal<T extends object>(obj: T, key: string, initialState: boolean): Signal;
+export declare function peekSignal<T extends object>(obj: T, key: string): Signal | undefined;
+export {};
+//# sourceMappingURL=-private.d.ts.map

package/unstable-preview-types/-private.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"-private.d.ts","sourceRoot":"","sources":["../src/-private.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAMzD;;;;;;;;;;;;;GAaG;AACH,KAAK,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAChD,KAAK,GAAG,GAAG;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAmCrC;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAYjD;AA6GD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAMxD;AACD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAMvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAKtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAKrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,CAOjG;AAED,eAAO,MAAM,OAAO,eAAoB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,QA0B9E;AAED,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,CAAC,EAAE,OAAO,CAAC;IAEX;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;IAEvC;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG,IAAI,CAAC;IAC/C;;;;;;;OAOG;IACH,SAAS,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG,IAAI,CAAC;IAEpD;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,QAKvE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA6B1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ1G;AAMD,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAe9F;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKpF"}

package/unstable-preview-types/index.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="ember-source/types" />
+/// <reference types="ember-source/types" />
+import { createCache, getValue } from '@glimmer/tracking/primitives/cache';
+export { transact, memoTransact, untracked } from './-private';
+export { dependentKeyCompat as compat } from '@ember/object/compat';
+export declare function cached<T extends object, K extends keyof T & string>(target: T, key: K, descriptor: PropertyDescriptor): void;
+export { createCache, getValue };
+//# sourceMappingURL=index.d.ts.map

package/unstable-preview-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AACA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI/D,OAAO,EAAE,kBAAkB,IAAI,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEpE,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EACjE,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,CAAC,EACN,UAAU,EAAE,kBAAkB,QA6B/B;AAED,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC"}