A platform for community discussion. Free, open, simple.
DEV: Convert `tracked-tools` to TypeScript (#45045)
Sérgio Saquetim02bcc69ea6f5
diff --git a/frontend/discourse/app/components/composer-messages.gjs b/frontend/discourse/app/components/composer-messages.gjsindex a5b1c474c64..7e23eb69cea 100644--- a/frontend/discourse/app/components/composer-messages.gjs+++ b/frontend/discourse/app/components/composer-messages.gjs@@ -18,7 +18,7 @@ import LinkLookup from "discourse/lib/link-lookup";import { userPath } from "discourse/lib/url";import dConcatClass from "discourse/ui-kit/helpers/d-concat-class";import { i18n } from "discourse-i18n";-import { autoTrackedArray } from "../lib/tracked-tools.js";+import { autoTrackedArray } from "../lib/tracked-tools.ts";let _messagesCache = {};let _educationMessageShown = false;diff --git a/frontend/discourse/app/lib/tracked-tools.js b/frontend/discourse/app/lib/tracked-tools.tssimilarity index 63%rename from frontend/discourse/app/lib/tracked-tools.jsrename to frontend/discourse/app/lib/tracked-tools.tsindex 30300c62cb4..06bd8f4e096 100644--- a/frontend/discourse/app/lib/tracked-tools.js+++ b/frontend/discourse/app/lib/tracked-tools.ts@@ -1,6 +1,12 @@import { setCustomTagFor } from "@glimmer/manager";import { tracked } from "@glimmer/tracking";-import { dirtyTagFor, tagFor, track, updateTag } from "@glimmer/validator";+import {+ dirtyTagFor,+ tagFor,+ track,+ type UpdatableTag,+ updateTag,+} from "@glimmer/validator";import { meta as metaFor, peekMeta } from "@ember/-internals/meta";import { TrackedDescriptor } from "@ember/-internals/metal";import {@@ -10,18 +16,53 @@ import {} from "@ember/reactive/collections";import { next } from "@ember/runloop";+/** Babel's legacy field descriptor, with values kept unknown until validated. */+interface FieldDescriptor<Value = unknown> {+ initializer?: (this: object) => Value;+ get?: (this: object) => Value;+ set?: (this: object, value: Value) => void;+ value?: Value;+ writable?: boolean;+ enumerable?: boolean;+ configurable?: boolean;+ isTracked?: boolean;+}++/** Accessors returned by the legacy tracked field decorators. */+interface TrackedAccessor<Value = unknown> {+ get: (this: object) => Value;+ set: (this: object, value: Value) => void;+}++/**+ * TODO(typescript-pending): Ember's descriptor overload permits undefined and+ * untyped accessors, and omits isTracked. Remove when it exposes the field+ * decorator's guaranteed accessors and preserves the initializer's value type.+ */+type TrackedFieldDecorator = <Value>(+ target: object,+ key: string,+ desc: FieldDescriptor<Value>+) => TrackedAccessor<Value>;++type ArrayValue = readonly unknown[] | null | undefined;+/**- * Define a tracked property on an object without needing to use the @tracked decorator.+ * Define a tracked property on an object without needing to use the `@tracked` decorator.* Useful when meta-programming the creation of properties on an object.** This must be run before the property is first accessed, so it normally makes sense for* this to only be called from a constructor.*/-export function defineTrackedProperty(target, key, value) {+export function defineTrackedProperty(+ target: object,+ key: string,+ value: unknown+): void {Object.defineProperty(target,key,- tracked(target, key, { enumerable: true, value })+ (tracked as TrackedFieldDecorator)(target, key, { enumerable: true, value }));}@@ -39,11 +80,10 @@ export function defineTrackedProperty(target, key, value) {* 1. Registers `setCustomTagFor` so `tagForProperty()` bypasses `setupMandatorySetter`* 2. Intercepts `set` to also call `dirtyTagFor()` for classic chain tag invalidation*- * @template {object} T- * @param {T} obj - The object to wrap in a tracked proxy.- * @returns {T} A proxy that supports both native autotracking and classic `@computed` chains.+ * @param obj - The object to wrap in a tracked proxy.+ * @returns A proxy that supports both native autotracking and classic `@computed` chains.*/-export function trackedObjectWithComputedSupport(obj) {+export function trackedObjectWithComputedSupport<T extends object>(obj: T): T {const inner = trackedObject(obj);const outer = new Proxy(inner, {@@ -60,11 +100,14 @@ export function trackedObjectWithComputedSupport(obj) {}class ResettableTrackedState {- @tracked currentValue;- previousUpstreamValue;+ @tracked currentValue: unknown;+ previousUpstreamValue: unknown;}-function getOrCreateState(map, instance) {+function getOrCreateState(+ map: WeakMap<object, ResettableTrackedState>,+ instance: object+): ResettableTrackedState {let state = map.get(instance);if (!state) {state = new ResettableTrackedState();@@ -94,15 +137,26 @@ function getOrCreateState(map, instance) {* `this.args.fullName`.**/-export function resettableTracked(prototype, key, descriptor) {+export function resettableTracked(prototype: object, key: string): void;+export function resettableTracked(+ prototype: object,+ key: string,+ descriptor: FieldDescriptor+): TrackedAccessor;+export function resettableTracked(+ prototype: object,+ key: string,+ descriptor?: FieldDescriptor+): TrackedAccessor {+ // Babel supplies the descriptor even though TypeScript checks fields with two arguments.// One WeakMap per-property-per-class. Keys are instances of the class- const states = new WeakMap();+ const states = new WeakMap<object, ResettableTrackedState>();return {- get() {+ get(this: object) {const state = getOrCreateState(states, this);- const upstreamValue = descriptor.initializer?.call(this);+ const upstreamValue = descriptor!.initializer?.call(this);if (upstreamValue !== state.previousUpstreamValue) {state.currentValue = upstreamValue;@@ -112,7 +166,7 @@ export function resettableTracked(prototype, key, descriptor) {return state.currentValue;},- set(value) {+ set(this: object, value: unknown) {const state = getOrCreateState(states, this);state.currentValue = value;},@@ -139,16 +193,27 @@ export function resettableTracked(prototype, key, descriptor) {* ```**/-export function dedupeTracked(target, key, desc) {- let { initializer } = desc;- let { get, set } = tracked(target, key, desc);-- let values = new WeakMap();+export function dedupeTracked(target: object, key: string): void;+export function dedupeTracked(+ target: object,+ key: string,+ desc: FieldDescriptor+): TrackedAccessor;+export function dedupeTracked(+ target: object,+ key: string,+ desc?: FieldDescriptor+): TrackedAccessor {+ // Babel supplies desc even though TypeScript checks fields with two arguments.+ const { initializer } = desc!;+ const { get, set } = (tracked as TrackedFieldDecorator)(target, key, desc!);++ const values = new WeakMap<object, unknown>();return {- get() {+ get(this: object) {if (!values.has(this)) {- let value = initializer?.call(this);+ const value = initializer?.call(this);values.set(this, value);set.call(this, value);}@@ -156,7 +221,7 @@ export function dedupeTracked(target, key, desc) {return get.call(this);},- set(value) {+ set(this: object, value: unknown) {if (!values.has(this) || values.get(this) !== value) {values.set(this, value);set.call(this, value);@@ -165,56 +230,56 @@ export function dedupeTracked(target, key, desc) {};}-export class DeferredTrackedSet {- #set;+export class DeferredTrackedSet<T = unknown> {+ #set: Set<T>;- constructor(value) {+ constructor(value?: Iterable<T> | null) {this.#set = trackedSet(value);}- get size() {+ get size(): number {return this.#set.size;}- get [Symbol.toStringTag]() {+ get [Symbol.toStringTag](): string {return this.#set[Symbol.toStringTag];}- has(value) {+ has(value: T): boolean {return this.#set.has(value);}- entries() {+ entries(): SetIterator<[T, T]> {return this.#set.entries();}- keys() {+ keys(): SetIterator<T> {return this.#set.keys();}- values() {+ values(): SetIterator<T> {return this.#set.values();}- forEach(fn) {+ forEach(fn: (value: T, value2: T, set: Set<T>) => void): void {return this.#set.forEach(fn);}- [Symbol.iterator]() {+ [Symbol.iterator](): SetIterator<T> {return this.#set[Symbol.iterator]();}- add(value) {+ add(value: T): this {next(() => this.#set.add(value));return this;}- delete(value) {+ delete(value: T): this {next(() => this.#set.delete(value));return this;}- clear() {+ clear(): void {next(() => this.#set.clear());}}@@ -233,22 +298,25 @@ const trackedArrayPrototype = Object.getPrototypeOf(trackedArray());* `@ember-compat/tracked-built-ins`. Only arrays produced by Ember's* `trackedArray()` function share the prototype used for detection.*- * @param {unknown} value - The value to check.- * @returns {boolean} `true` if the value is a tracked array, `false` otherwise.+ * @param value - The value to check.+ * @returns `true` if the value is a tracked array, `false` otherwise.*/-export function isTrackedArray(value) {+export function isTrackedArray(value: unknown): value is unknown[] {return value != null && trackedArrayPrototype.isPrototypeOf(value);}/*** Converts a value to TrackedArray if needed and validates the type.*- * @param {TrackedArray|Array|null|undefined} value - Value to convert- * @returns {TrackedArray|null|undefined} - Returns the value converted to TrackedArray if needed,+ * @param value - Value to convert+ * @returns - Returns the value converted to TrackedArray if needed,* or null/undefined if those values were passed- * @throws {Error} If value is not an array, TrackedArray, null or undefined+ * @throws Error if value is not an array, TrackedArray, null or undefined*/-function ensureTrackedArray(value, propertyName) {+function ensureTrackedArray(+ value: unknown,+ propertyName: string+): unknown[] | null | undefined {if (typeof value === "undefined" || value === null) {return value;}@@ -270,33 +338,53 @@ function ensureTrackedArray(value, propertyName) {* @decorator* Same as `@tracked`, but initializes the value as a TrackedArray.*- * @param {object} target - The target object- * @param {string|symbol} key - The property key- * @param {{ initializer?: () => unknown, get?: () => unknown, set?: (value: unknown) => void, value?: unknown, writable?: boolean, enumerable?: boolean, configurable?: boolean }} desc - The property descriptor- * @returns {{ get: () => unknown, set: (value: unknown) => void, enumerable: boolean, configurable: boolean, isTracked: boolean }} Modified property descriptor that wraps arrays in TrackedArray+ * @param target - The target object+ * @param key - The property key+ * @param desc - The property descriptor+ * @returns Modified property descriptor that wraps arrays in TrackedArray** @example+ * ```js* class TodoList {* @autoTrackedArray todos = ['Buy milk', 'Walk dog'];* }+ * ```*/-export function autoTrackedArray(target, key, desc) {- if (desc.initializer) {- const originalInitializer = desc.initializer;- desc.initializer = function () {+export function autoTrackedArray<Key extends string>(+ target: { [Property in Key]?: ArrayValue },+ key: Key+): void;+export function autoTrackedArray(+ target: object,+ key: string,+ desc: FieldDescriptor<ArrayValue>+): TrackedAccessor<ArrayValue> & {+ enumerable: boolean;+ configurable: boolean;+ isTracked: boolean;+};+export function autoTrackedArray(+ target: object,+ key: string,+ desc?: FieldDescriptor<ArrayValue>+) {+ // Babel supplies desc even though TypeScript checks fields with two arguments.+ if (desc!.initializer) {+ const originalInitializer = desc!.initializer;+ desc!.initializer = function () {const initialValue = originalInitializer.apply(this);return ensureTrackedArray(initialValue, key);};}- const { get, set } = tracked(target, key, {+ const { get, set } = (tracked as TrackedFieldDecorator)(target, key, {...desc,enumerable: true,configurable: true,isTracked: true,});- function autoTrackedArraySetter(value) {+ function autoTrackedArraySetter(this: object, value: unknown) {set.call(this, ensureTrackedArray(value, key));}@@ -309,7 +397,7 @@ export function autoTrackedArray(target, key, desc) {// that are already @tracked). The getter captures the TrackedArray's// collection tag via track(), then updates tagFor(obj, key) so that// @computed properties watching this key see content changes.- function autoTrackedArrayGetter() {+ function autoTrackedArrayGetter(this: object) {// Read the value outside track() to avoid a tag cycle. get.call(this)// consumes the property's own tag (tagFor(this, key)) via the tracked// storage. If we captured that inside track() and then called updateTag@@ -324,7 +412,9 @@ export function autoTrackedArray(target, key, desc) {// setValue(collection, null).const propertyTag = tagFor(this, key);const collectionTag = track(() => value.length);- updateTag(propertyTag, collectionTag);+ // TODO(typescript-pending): tagFor's declared ConstantTag union is broader+ // than its implementation, which creates UpdatableTags. Remove when aligned.+ updateTag(propertyTag as UpdatableTag, collectionTag);}return value;@@ -357,11 +447,12 @@ export { autoTrackedArray as trackedArray };* **Warning:** This function uses Ember internal APIs (`peekMeta`, `TrackedDescriptor`)* which are not part of the public API and may change without notice in future Ember versions.*- * @param {object | null | undefined} obj - The object instance to enumerate tracked keys from- * @returns {Array<string>} An array of tracked property keys.+ * @param obj - The object instance to enumerate tracked keys from+ * @returns An array of tracked property keys.* Returns an empty array if the object has no prototype or no tracked properties.** @example+ * ```js* class MyClass {* @tracked name = "Alice";* @tracked age = 30;@@ -371,14 +462,15 @@ export { autoTrackedArray as trackedArray };* const instance = new MyClass();* const trackedKeys = enumerateTrackedKeys(instance);* // Returns: ["name", "age"]+ * ```*/-export function enumerateTrackedKeys(obj) {+export function enumerateTrackedKeys(obj: object | null | undefined): string[] {const prototype = obj?.constructor?.prototype;if (!prototype) {return [];}- const result = new Set();+ const result = new Set<string>();// Walk the prototype chain to collect tracked keys from parent classes toolet meta = peekMeta(prototype);@@ -405,11 +497,12 @@ export function enumerateTrackedKeys(obj) {* **Warning:** This function uses Ember internal APIs (`peekMeta`, `TrackedDescriptor`)* which are not part of the public API and may change without notice in future Ember versions.*- * @param {object | null | undefined} obj - The object instance to enumerate tracked entries from- * @returns {Array<[string, unknown]>} An array of [key, value] pairs for all tracked properties.+ * @param obj - The object instance to enumerate tracked entries from+ * @returns An array of [key, value] pairs for all tracked properties.* Returns an empty array if the object has no prototype or no tracked properties.** @example+ * ```js* class MyClass {* @tracked name = "Alice";* @tracked age = 30;@@ -419,10 +512,15 @@ export function enumerateTrackedKeys(obj) {* const instance = new MyClass();* const trackedEntries = enumerateTrackedEntries(instance);* // Returns: [["name", "Alice"], ["age", 30]]+ * ```*/-export function enumerateTrackedEntries(obj) {+export function enumerateTrackedEntries(+ obj: object | null | undefined+): [string, unknown][] {const keys = enumerateTrackedKeys(obj);- return keys.map((key) => [key, obj[key]]);+ // Tracked keys come from Ember's dynamic descriptor registry, not keyof obj.+ // A nullish obj produces no keys, so the callback only indexes an object.+ return keys.map((key) => [key, (obj as Record<string, unknown>)[key]]);}/**@@ -433,7 +531,6 @@ export function enumerateTrackedEntries(obj) {** Consuming state you do not use is generally a violation of Ember's declarative* patterns, so reach for this only when absolutely necessary.- *- * @type {(value: unknown) => void}*/+export function manuallyTrack(value: unknown): void;export function manuallyTrack() {}diff --git a/frontend/discourse/type-tests/lib/tracked-tools-test.ts b/frontend/discourse/type-tests/lib/tracked-tools-test.tsnew file mode 100644index 00000000000..3ea9019f6b8--- /dev/null+++ b/frontend/discourse/type-tests/lib/tracked-tools-test.ts@@ -0,0 +1,96 @@+import { expectTypeOf } from "expect-type";+import {+ autoTrackedArray,+ dedupeTracked,+ DeferredTrackedSet,+ defineTrackedProperty,+ enumerateTrackedEntries,+ enumerateTrackedKeys,+ isTrackedArray,+ manuallyTrack,+ resettableTracked,+ // eslint-disable-next-line discourse/deprecated-imports -- asserts the deprecated alias keeps its type+ trackedArray,+ trackedObjectWithComputedSupport,+} from "discourse/lib/tracked-tools";++// The decorators run as legacy field decorators, so TypeScript checks them as+// `(target, key)` calls returning `void`. Every field form below must compile.+export class Decorated {+ @autoTrackedArray tags: string[] = [];+ @autoTrackedArray maybeTags?: string[];+ @autoTrackedArray nullableTags: number[] | null = null;+ @autoTrackedArray readonlyTags: readonly string[] = [];+ @trackedArray legacyTags: string[] = [];++ @dedupeTracked name = "";+ @dedupeTracked count?: number;++ @resettableTracked label = "";+ @resettableTracked selection: { id: number } | null = null;+}++// `autoTrackedArray` throws at runtime for anything but an array, null or+// undefined, so a non-array field is a compile error.+export class NotAnArray {+ // @ts-expect-error a string field cannot hold a tracked array+ @autoTrackedArray name = "";++ // @ts-expect-error an object field cannot hold a tracked array+ @autoTrackedArray settings: { enabled: boolean } = { enabled: false };+}++// The deprecated alias is the same function.+expectTypeOf(trackedArray).toEqualTypeOf(autoTrackedArray);++// `trackedObjectWithComputedSupport` returns a proxy with the input's shape.+const tracked = trackedObjectWithComputedSupport({ id: 1, title: "x" });+expectTypeOf(tracked).toEqualTypeOf<{ id: number; title: string }>();+expectTypeOf(tracked).not.toBeAny();+// @ts-expect-error only objects can be proxied+trackedObjectWithComputedSupport("not an object");++// `DeferredTrackedSet` defers mutations to the next run loop, so `add` and+// `delete` return the set rather than a boolean.+const deferred = new DeferredTrackedSet<string>();+expectTypeOf(deferred.add("a")).toEqualTypeOf<DeferredTrackedSet<string>>();+expectTypeOf(deferred.delete("a")).toEqualTypeOf<DeferredTrackedSet<string>>();+expectTypeOf(deferred.has("a")).toEqualTypeOf<boolean>();+expectTypeOf(deferred.size).toEqualTypeOf<number>();+expectTypeOf(deferred.clear()).toEqualTypeOf<void>();+expectTypeOf([...deferred]).toEqualTypeOf<string[]>();+expectTypeOf([...deferred.values()]).toEqualTypeOf<string[]>();+expectTypeOf([...deferred.keys()]).toEqualTypeOf<string[]>();+expectTypeOf([...deferred.entries()]).toEqualTypeOf<[string, string][]>();+deferred.forEach((value) => expectTypeOf(value).toEqualTypeOf<string>());+// @ts-expect-error the set only holds strings+deferred.add(1);+expectTypeOf(new DeferredTrackedSet(["a", "b"])).toEqualTypeOf<+ DeferredTrackedSet<string>+>();+// An untyped set, as `services/breadcrumbs.js` creates, holds unknown values.+expectTypeOf(new DeferredTrackedSet()).toEqualTypeOf<+ DeferredTrackedSet<unknown>+>();++// `isTrackedArray` narrows to an array.+declare const maybeArray: unknown;+expectTypeOf(isTrackedArray(maybeArray)).toEqualTypeOf<boolean>();+if (isTrackedArray(maybeArray)) {+ expectTypeOf(maybeArray).toEqualTypeOf<unknown[]>();+}++// The enumerators accept a missing object and return keys or entries.+declare const instance: object | null | undefined;+expectTypeOf(enumerateTrackedKeys(instance)).toEqualTypeOf<string[]>();+expectTypeOf(enumerateTrackedEntries(instance)).toEqualTypeOf<+ [string, unknown][]+>();+// @ts-expect-error a primitive has no tracked properties to enumerate+enumerateTrackedKeys("text");++expectTypeOf(defineTrackedProperty({}, "title", "x")).toEqualTypeOf<void>();+// @ts-expect-error the target must be an object+defineTrackedProperty("text", "title", "x");++expectTypeOf(manuallyTrack(tracked.title)).toEqualTypeOf<void>();