@esportsplus/reactivity 0.37.2 → 0.38.1

package/src/compiler/bindings.ts

@@ -1,100 +1,303 @@
 import { ts } from '@esportsplus/typescript';
-import { TYPES } from './constants';
+import { references } from '@esportsplus/typescript/compiler';
+import type { Origin } from '@esportsplus/typescript/compiler';
+import { ENTRYPOINT, PACKAGE_NAME, TYPES } from './constants';
 import type { Bindings } from './types';
 
 
-function root(expression: ts.Expression): { path: string; root: ts.Identifier } | null {
-    let parts: string[] = [];
+type Assignment = { call: ts.CallExpression; target: ts.Identifier };
 
-    while (ts.isPropertyAccessExpression(expression)) {
-        parts.push(expression.name.text);
-        expression = expression.expression;
+// Per program snapshot: answers about declarations and types hold for the snapshot's lifetime
+type Caches = {
+    arrays: Map<number, boolean>;
+    assignments: Map<string, Map<string, Assignment[]>>;
+    kinds: Map<string, TYPES | null>;
+};
+
+
+const ARRAY_BRAND = 'once';
+
+const REACTIVE_ARRAY = 'ReactiveArray';
+
+
+let caches = new WeakMap<ts.Program, Caches>();
+
+
+// `x = reactive(...)` assignments in a file, keyed by the assigned name: a variable declared
+// without a reactive initializer becomes a binding through one of these
+function assignments(bindings: Bindings, file: ts.SourceFile): Map<string, Assignment[]> {
+    let cache = cachesOf(bindings.program).assignments,
+        found = cache.get(file.fileName);
+
+    if (found) {
+        return found;
     }
 
-    if (!ts.isIdentifier(expression) || parts.length === 0) {
-        return null;
+    let result = new Map<string, Assignment[]>(),
+        visit = (node: ts.Node): void => {
+            if (
+                ts.isBinaryExpression(node) &&
+                node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                ts.isIdentifier(node.left)
+            ) {
+                let call = unwrap(node.right);
+
+                if (ts.isCallExpression(call)) {
+                    let list = result.get(node.left.text);
+
+                    if (!list) {
+                        list = [];
+                        result.set(node.left.text, list);
+                    }
+
+                    list.push({ call, target: node.left });
+                }
+            }
+
+            node.forEachChild(visit);
+        };
+
+    visit(file);
+    cache.set(file.fileName, result);
+
+    return result;
+}
+
+function cachesOf(program: ts.Program): Caches {
+    let found = caches.get(program);
+
+    if (!found) {
+        found = { arrays: new Map(), assignments: new Map(), kinds: new Map() };
+        caches.set(program, found);
     }
 
-    return { path: parts.reverse().join('.'), root: expression };
+    return found;
 }
 
-function symbolOf(bindings: Bindings, identifier: ts.Identifier): ts.Symbol | undefined {
-    let parent = identifier.parent;
+// Every member of a union must agree: `number | undefined` is a signal, `number[] | undefined` is
+// neither a signal nor an array at runtime
+function kindOf(checker: ts.Checker, type: ts.Type): TYPES | null {
+    let members = (type.flags & ts.TypeFlags.Union) !== 0 ? (type as ts.UnionType).getTypes() : [type],
+        result: TYPES | null = null;
+
+    for (let i = 0, n = members.length; i < n; i++) {
+        let kind = kindOfType(checker, members[i]);
 
-    // A shorthand property's own symbol is the object property, not the variable it reads
-    if (parent && ts.isShorthandPropertyAssignment(parent) && parent.name === identifier) {
-        return bindings.checker.getShorthandAssignmentValueSymbol(parent);
+        if (kind === null || (result !== null && result !== kind)) {
+            return null;
+        }
+
+        result = kind;
     }
 
-    return bindings.checker.getSymbolAtLocation(identifier);
+    return result;
 }
 
+// Kind of one non-union type as a reactive() argument; null when the type cannot say
+function kindOfType(checker: ts.Checker, type: ts.Type): TYPES | null {
+    if ((type.flags & ts.TypeFlags.TypeParameter) !== 0) {
+        let constraint = checker.getBaseConstraintOfType(type);
 
-// Bindings are keyed by symbol, so a shadowing local, parameter or property that merely shares a
-// reactive variable's name is never rewritten. `names` keeps resolution cheap: an identifier whose
-// text no reactive declaration uses cannot refer to one, so it never costs a checker round-trip.
-const create = (checker: ts.Checker): Bindings => ({
-    checker,
-    names: new Set(),
-    paths: new Map(),
-    symbols: new Map()
-});
+        return constraint && constraint !== type ? kindOf(checker, constraint) : null;
+    }
+
+    if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Never | ts.TypeFlags.Unknown)) !== 0) {
+        return null;
+    }
 
-const declare = (bindings: Bindings, identifier: ts.Identifier, type: TYPES): void => {
-    let symbol = bindings.checker.getSymbolAtLocation(identifier);
+    if ((type.flags & (
+        ts.TypeFlags.BigIntLike |
+        ts.TypeFlags.BooleanLike |
+        ts.TypeFlags.EnumLike |
+        ts.TypeFlags.ESSymbolLike |
+        ts.TypeFlags.Null |
+        ts.TypeFlags.NumberLike |
+        ts.TypeFlags.StringLike |
+        ts.TypeFlags.TemplateLiteral |
+        ts.TypeFlags.Undefined |
+        ts.TypeFlags.Void
+    )) !== 0) {
+        return TYPES.Signal;
+    }
 
-    if (symbol) {
-        bindings.names.add(identifier.text);
-        bindings.symbols.set(symbol, type);
+    if (checker.isArrayType(type) || checker.isTupleType(type)) {
+        return TYPES.Array;
     }
-};
 
-// `state.items` where `state` is a reactive object whose `items` property is a ReactiveArray
-const declarePath = (bindings: Bindings, identifier: ts.Identifier, path: string): void => {
-    let symbol = bindings.checker.getSymbolAtLocation(identifier);
+    if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0) {
+        return TYPES.Computed;
+    }
+
+    return (type.flags & (ts.TypeFlags.Intersection | ts.TypeFlags.NonPrimitive | ts.TypeFlags.Object)) !== 0 ? TYPES.Object : null;
+}
+
+
+
+// Expressions whose type is a ReactiveArray (`Reactive<T[]>` carries the class's members), resolved
+// in one checker round-trip. Found by type, a reactive array is recognized wherever it flows:
+// imports, object properties, parameters, return values.
+const arrays = (bindings: Bindings, nodes: ts.Node[]): Set<ts.Node> => {
+    let result = new Set<ts.Node>();
 
-    if (!symbol) {
-        return;
+    if (nodes.length === 0) {
+        return result;
     }
 
-    let paths = bindings.paths.get(symbol);
+    let files = new Set(references.exported(bindings.checker, bindings.program, PACKAGE_NAME, REACTIVE_ARRAY).map(declaration => declaration.path));
 
-    if (!paths) {
-        paths = new Set();
-        bindings.paths.set(symbol, paths);
+    if (files.size === 0) {
+        return result;
     }
 
-    bindings.names.add(identifier.text);
-    paths.add(path);
+    let cache = cachesOf(bindings.program).arrays,
+        types = bindings.checker.getTypeAtLocation(nodes);
+
+    for (let i = 0, n = nodes.length; i < n; i++) {
+        let type = types[i];
+
+        if (!type) {
+            continue;
+        }
+
+        let branded = cache.get(type.id);
+
+        if (branded === undefined) {
+            let property = bindings.checker.getPropertyOfType(bindings.checker.getNonNullableType(type) ?? type, ARRAY_BRAND);
+
+            branded = property?.declarations?.some(declaration => files.has(declaration.path)) === true;
+            cache.set(type.id, branded);
+        }
+
+        if (branded) {
+            result.add(nodes[i]);
+        }
+    }
+
+    return result;
 };
 
-// True for an identifier or property path that denotes a ReactiveArray binding
-const isArray = (bindings: Bindings, expression: ts.Expression): boolean => {
-    if (ts.isIdentifier(expression)) {
-        return resolve(bindings, expression)?.type === TYPES.Array;
+// Kind of a reactive() call from its argument: literal syntax first, the argument's type otherwise.
+// Null when no kind is provable (no/extra arguments, `any`, `unknown`, a mixed union).
+const classify = (bindings: Bindings, call: ts.CallExpression): TYPES | null => {
+    let arg = call.arguments[0];
+
+    if (!arg || call.arguments.length !== 1 || ts.isSpreadElement(arg)) {
+        return null;
+    }
+
+    let value = unwrap(arg);
+
+    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) {
+        return TYPES.Computed;
     }
 
-    let access = root(expression);
+    if (ts.isArrayLiteralExpression(value)) {
+        return TYPES.Array;
+    }
 
-    if (!access || !bindings.names.has(access.root.text)) {
-        return false;
+    if (ts.isObjectLiteralExpression(value)) {
+        return TYPES.Object;
     }
 
-    let symbol = symbolOf(bindings, access.root);
+    let type = bindings.checker.getTypeAtLocation(arg);
+
+    return type ? kindOf(bindings.checker, type) : null;
+};
+
+const create = (checker: ts.Checker, program: ts.Program, sourceFile: ts.SourceFile): Bindings => ({
+    checker,
+    entries: new Set(references.exported(checker, program, PACKAGE_NAME, ENTRYPOINT).map(references.key)),
+    origins: references.origins(checker, program, sourceFile),
+    program,
+    sourceFile
+});
+
+// Whether a callee expression denotes `reactive`: `reactive`, an alias, `ns.reactive`, `ns['reactive']`
+const denotes = (bindings: Bindings, expression: ts.Expression): boolean => {
+    return references.denotes(bindings.checker, bindings.program, expression, bindings.entries);
+};
+
+// Whether a value holds `reactive`: the export itself, reached through any import, re-export or
+// namespace, or a const binding (`const r = reactive`, `const { reactive: r } = ns`) holding it
+const holds = (bindings: Bindings, found: Origin | null): boolean => {
+    return references.holds(bindings.checker, bindings.program, found, bindings.entries);
+};
 
-    return symbol !== undefined && bindings.paths.get(symbol)?.has(access.path) === true;
+const isReactiveCall = (bindings: Bindings, node: ts.Node): node is ts.CallExpression => {
+    return ts.isCallExpression(node) && denotes(bindings, node.expression);
 };
 
-const resolve = (bindings: Bindings, identifier: ts.Identifier): { symbol: ts.Symbol; type: TYPES } | null => {
-    if (!bindings.names.has(identifier.text)) {
+// Reactive kind of the binding a declaration introduces, wherever it is read from: a variable
+// initialized (or assigned) with reactive(), or a module's `export default reactive(...)`.
+// Ambient declarations (.d.ts) never are: a published package's signals ship as Signal-typed.
+const kind = (bindings: Bindings, found: Origin | null): TYPES | null => {
+    if (!found) {
         return null;
     }
 
-    let symbol = symbolOf(bindings, identifier),
-        type = symbol && bindings.symbols.get(symbol);
+    let declaration = found.declaration;
+
+    if (
+        (declaration.kind !== ts.SyntaxKind.VariableDeclaration && declaration.kind !== ts.SyntaxKind.ExportAssignment) ||
+        declaration.path.endsWith('.d.ts')
+    ) {
+        return null;
+    }
+
+    let cache = cachesOf(bindings.program).kinds,
+        key = references.key(declaration),
+        known = cache.get(key);
+
+    if (known !== undefined) {
+        return known;
+    }
+
+    cache.set(key, null);
+
+    let node = declaration.resolve() as ts.Node | undefined,
+        result: TYPES | null = null;
+
+    if (node && ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+        let initializer = node.initializer && unwrap(node.initializer);
+
+        if (initializer && isReactiveCall(bindings, initializer)) {
+            result = classify(bindings, initializer);
+        }
+        else {
+            let candidates = assignments(bindings, node.getSourceFile()).get(node.name.text) ?? [];
+
+            for (let i = 0, n = candidates.length; i < n && result === null; i++) {
+                let { call, target } = candidates[i],
+                    assigned = origin(bindings, target);
+
+                if (assigned && references.key(assigned.declaration) === key && isReactiveCall(bindings, call)) {
+                    result = classify(bindings, call);
+                }
+            }
+        }
+    }
+    else if (node && ts.isExportAssignment(node)) {
+        let expression = unwrap(node.expression);
+
+        if (isReactiveCall(bindings, expression)) {
+            result = classify(bindings, expression);
+        }
+    }
+
+    cache.set(key, result);
+
+    return result;
+};
+
+const origin = (bindings: Bindings, node: ts.Node): Origin | null => {
+    return bindings.origins.get(node) ?? references.origin(bindings.checker, bindings.program, node);
+};
+
 
-    return symbol && type !== undefined ? { symbol, type } : null;
+// The expression a value comes from, without parentheses, `!` and type assertions
+const unwrap = (expression: ts.Expression): ts.Expression => {
+    return references.unwrap(expression) as ts.Expression;
 };
 
 
-export default { create, declare, declarePath, isArray, resolve };
+export default { arrays, classify, create, denotes, holds, isReactiveCall, kind, origin, unwrap };

package/src/compiler/constants.ts

@@ -28,6 +28,7 @@ const NAMESPACE = uid('reactivity');
 const TYPES = {
     Array: 0,
     Computed: 1,
+    Object: 3,
     Signal: 2
 } as const;
 

package/src/compiler/index.ts

@@ -1,7 +1,7 @@
 import { ts } from '@esportsplus/typescript';
-import { imports } from '@esportsplus/typescript/compiler';
 import type { ImportIntent, ReplacementIntent, TransformContext } from '@esportsplus/typescript/compiler';
 import { ENTRYPOINT, NAMESPACE, PACKAGE_NAME } from './constants';
+import type { Failure } from './primitives';
 
 import array from './array';
 import object from './object';
@@ -9,81 +9,170 @@ import primitives from './primitives';
 import scope from './bindings';
 
 
-// Resolved once per file: every pass asks the same question of the same nodes
-function collect(checker: ts.Checker, node: ts.Node, calls: Set<ts.Node>): void {
-    if (isReactiveCallExpression(checker, node)) {
-        calls.add(node);
+// Every use the compiler cannot lower fails the build, all of them reported at once: shipping one
+// would leave an uncompiled reactive() or an unread signal in the output
+function failed(sourceFile: ts.SourceFile, failures: Failure[]): Error {
+    let lines: string[] = [];
+
+    for (let i = 0, n = failures.length; i < n; i++) {
+        let { message, node } = failures[i],
+            position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+
+        lines.push(`  ${sourceFile.fileName}:${position.line + 1}:${position.character + 1}  ${message}: ${node.getText(sourceFile).split('\n')[0]}`);
     }
 
-    node.forEachChild(child => collect(checker, child, calls));
+    return new Error(`${PACKAGE_NAME}: code that must be compiled cannot be:\n${lines.join('\n')}`);
+}
+
+function isConstList(node: ts.Node | undefined): boolean {
+    return node !== undefined && ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.Const) !== 0;
 }
 
-function isReactiveCallExpression(checker: ts.Checker, node: ts.Node): node is ts.CallExpression {
-    if (!ts.isCallExpression(node)) {
+// A use of `reactive` the compiler lowers: a callee, or a const alias whose own uses are sites
+function isLowered(site: ts.Node): boolean {
+    let parent = site.parent;
+
+    while (parent && ts.isParenthesizedExpression(parent)) {
+        site = parent;
+        parent = site.parent;
+    }
+
+    if (!parent) {
         return false;
     }
 
-    let expr = node.expression;
+    if (ts.isCallExpression(parent)) {
+        return parent.expression === site;
+    }
 
-    // Direct call: reactive(...) or aliasedName(...)
-    if (ts.isIdentifier(expr)) {
-        return imports.includes(checker, expr, PACKAGE_NAME, ENTRYPOINT);
+    if (ts.isVariableDeclaration(parent)) {
+        // `const r = reactive` only: destructuring would pull a member out of the compiled value
+        return parent.initializer === site && ts.isIdentifier(parent.name) && isConstList(parent.parent);
     }
 
-    // Namespace call: ns.reactive(...) — the namespace identifier carries the import origin
-    if (ts.isPropertyAccessExpression(expr) && expr.name.text === ENTRYPOINT && ts.isIdentifier(expr.expression)) {
-        return imports.includes(checker, expr.expression, PACKAGE_NAME);
+    if (ts.isBindingElement(parent) && parent.propertyName === site) {
+        let declaration: ts.Node | undefined = parent;
+
+        while (declaration && !ts.isVariableDeclaration(declaration)) {
+            declaration = declaration.parent;
+        }
+
+        return declaration !== undefined && isConstList(declaration.parent);
     }
 
     return false;
 }
 
 
+// `reactive`, or the member access naming it (`ns.reactive`, `ns['reactive']`)
+function siteOf(identifier: ts.Node): ts.Node {
+    let parent = identifier.parent!;
+
+    if (
+        (ts.isPropertyAccessExpression(parent) && parent.name === identifier) ||
+        (ts.isElementAccessExpression(parent) && parent.argumentExpression === identifier)
+    ) {
+        return parent;
+    }
+
+    return identifier;
+}
+
+
+// No text patterns: a module can reach `reactive`, or read a reactive binding, under any name
+// (a barrel's rename, a default re-export, a namespace), so every module is resolved against the
+// program and compiled exactly where its values resolve to reactive declarations
 export default {
-    patterns: ['reactive(', 'reactive<'],
     transform: (ctx: TransformContext) => {
-        let checker = ctx.checker;
+        let { checker, program, sourceFile } = ctx,
+            bindings = scope.create(checker, program, sourceFile),
+            calls = new Set<ts.Node>(),
+            dependencies = new Set<string>(),
+            failures: Failure[] = [],
+            self = sourceFile.fileName.toLowerCase();
+
+        for (let [identifier, found] of bindings.origins) {
+            let entry = scope.holds(bindings, found);
+
+            if (!entry && scope.kind(bindings, found) === null) {
+                continue;
+            }
+
+            for (let file of [...found.through, found.declaration.path]) {
+                if (file.toLowerCase() !== self) {
+                    dependencies.add(file);
+                }
+            }
 
-        if (!checker) {
-            return {};
+            if (!entry) {
+                continue;
+            }
+
+            let site = siteOf(identifier),
+                parent = site.parent;
+
+            while (parent && ts.isParenthesizedExpression(parent)) {
+                parent = parent.parent;
+            }
+
+            if (parent && ts.isCallExpression(parent) && scope.unwrap(parent.expression) === site) {
+                calls.add(parent);
+            }
+            else if (!isLowered(site)) {
+                failures.push({
+                    message: `${ENTRYPOINT} is compiled away, so it can only be called (or aliased with const); it cannot be used as a value`,
+                    node: site
+                });
+            }
         }
 
-        let bindings = scope.create(checker),
-            candidates = new Set<ts.Node>(),
+        let isReactiveCall = (node: ts.Node): node is ts.CallExpression => calls.has(node),
             intents = {
                 imports: [] as ImportIntent[],
                 prepend: [] as string[],
                 replacements: [] as ReplacementIntent[]
-            },
-            sourceFile = ctx.sourceFile;
+            };
 
-        collect(checker, sourceFile, candidates);
+        // Signals and computeds first: every call is classified and every binding read is rewritten
+        let lowered = primitives(sourceFile, bindings, isReactiveCall);
 
-        if (candidates.size === 0) {
-            return {};
-        }
-
-        let isReactiveCall = (node: ts.Node): node is ts.CallExpression => candidates.has(node);
-
-        // Run primitives transform first (tracks bindings for signal/computed, collects every call)
-        let { calls, replacements } = primitives(sourceFile, bindings, isReactiveCall);
+        failures.push(...lowered.failures);
+        intents.replacements.push(...lowered.replacements);
 
-        intents.replacements.push(...replacements);
-
-        // Run object transform
         let objects = object(sourceFile, bindings, isReactiveCall);
 
         intents.prepend.push(...objects.prepend);
         intents.replacements.push(...objects.replacements);
 
-        // Run array transform separately ( avoid race conditions )
-        intents.replacements.push(...array(sourceFile, bindings, isReactiveCall));
+        let arrays = array(sourceFile, bindings, isReactiveCall);
+
+        failures.push(...arrays.failures);
+        intents.replacements.push(...arrays.replacements);
+
+        // An array is reactive because of where it was declared; that module shapes this compile
+        for (let i = 0, n = arrays.reactive.length; i < n; i++) {
+            let root = arrays.reactive[i];
 
-        // Calls no transform claimed fall through to the runtime reactive()
+            while (ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root) || ts.isParenthesizedExpression(root)) {
+                root = root.expression;
+            }
+
+            let found = ts.isIdentifier(root) ? scope.origin(bindings, root) : null;
+
+            if (found && found.declaration.path.toLowerCase() !== self) {
+                dependencies.add(found.declaration.path);
+            }
+        }
+
+        if (failures.length > 0) {
+            throw failed(sourceFile, failures);
+        }
+
+        // An object literal the object transform cannot specialize (a spread) is built by the runtime
         let transformed = new Set(intents.replacements.map(r => r.node));
 
-        for (let i = 0, n = calls.length; i < n; i++) {
-            let call = calls[i];
+        for (let i = 0, n = lowered.calls.length; i < n; i++) {
+            let call = lowered.calls[i];
 
             if (transformed.has(call) || transformed.has(call.expression)) {
                 continue;
@@ -95,12 +184,19 @@ export default {
             });
         }
 
-        intents.imports.push({
-            namespace: NAMESPACE,
-            package: PACKAGE_NAME,
-            remove: [ENTRYPOINT]
-        });
+        if (intents.replacements.length === 0 && intents.prepend.length === 0) {
+            return dependencies.size > 0 ? { dependencies: [...dependencies] } : {};
+        }
+
+        // `.length` / element-write rewrites alone call methods on the array itself
+        if (calls.size > 0 || lowered.replacements.length > 0 || intents.prepend.length > 0 || arrays.namespaced) {
+            intents.imports.push({
+                namespace: NAMESPACE,
+                package: PACKAGE_NAME,
+                remove: [ENTRYPOINT]
+            });
+        }
 
-        return intents;
+        return { dependencies: [...dependencies], ...intents };
     }
 };