@esportsplus/reactivity 0.37.2 → 0.38.1

package/src/compiler/object.ts

@@ -3,7 +3,6 @@ import { code, uid } from '@esportsplus/typescript/compiler';
 import type { ReplacementIntent } from '@esportsplus/typescript/compiler';
 import { NAMESPACE, TYPES } from './constants';
 import type { Bindings, IsReactiveCall } from './types';
-import scope from './bindings';
 
 
 interface AnalyzedProperty {
@@ -34,7 +33,9 @@ interface VisitContext {
 }
 
 
-function analyzeProperty(prop: ts.ObjectLiteralElementLike, sourceFile: ts.SourceFile): AnalyzedProperty | null {
+function analyzeProperty(prop: ts.ObjectLiteralElementLike, bindings: Bindings): AnalyzedProperty | null {
+    let sourceFile = bindings.sourceFile;
+
     if (!ts.isPropertyAssignment(prop)) {
         return null;
     }
@@ -88,6 +89,14 @@ function analyzeProperty(prop: ts.ObjectLiteralElementLike, sourceFile: ts.Sourc
         return { isStatic, key, type: TYPES.Array, valueText };
     }
 
+    // A non-literal array is typed Reactive<T[]> on the object, so it must become a ReactiveArray
+    // exactly like a literal one
+    let type = isStaticValue(unwrapped) ? undefined : bindings.checker.getTypeAtLocation(value);
+
+    if (type && (bindings.checker.isArrayType(type) || bindings.checker.isTupleType(type))) {
+        return { isStatic: false, key, type: TYPES.Array, valueText };
+    }
+
     return {
         isStatic: isStaticValue(value),
         key,
@@ -224,10 +233,9 @@ function visit(ctx: VisitContext, node: ts.Node): void {
         if (arg && ts.isObjectLiteralExpression(arg)) {
             let properties: AnalyzedProperty[] = [],
                 props = arg.properties,
-                target = node.parent && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)
-                    ? node.parent.name
-                    : null,
-                varname = target?.text ?? null;
+                varname = node.parent && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)
+                    ? node.parent.name.text
+                    : null;
 
             for (let i = 0, n = props.length; i < n; i++) {
                 let prop = props[i];
@@ -237,7 +245,7 @@ function visit(ctx: VisitContext, node: ts.Node): void {
                     return;
                 }
 
-                let analyzed = analyzeProperty(prop, ctx.sourceFile);
+                let analyzed = analyzeProperty(prop, ctx.bindings);
 
                 if (!analyzed) {
                     node.forEachChild(n => visit(ctx, n));
@@ -247,15 +255,6 @@ function visit(ctx: VisitContext, node: ts.Node): void {
                 properties.push(analyzed);
             }
 
-            // Declared only once every property analyzed: a bailed object stays a runtime reactive()
-            if (target) {
-                for (let i = 0, n = properties.length; i < n; i++) {
-                    if (properties[i].type === TYPES.Array) {
-                        scope.declarePath(ctx.bindings, target, properties[i].key);
-                    }
-                }
-            }
-
             ctx.calls.push({
                 classname: uid('ReactiveObject'),
                 node,
@@ -290,8 +289,9 @@ export default (sourceFile: ts.SourceFile, bindings: Bindings, isReactiveCall: I
         prepend.push(buildClassCode(call.classname, call.properties, typehint));
         replacements.push({
             generate: () => {
+                // Every property but a static signal (baked into its field) is a constructor parameter
                 let args = call.properties
-                    .filter(({ isStatic, type }) => typehint || !isStatic || type === TYPES.Computed)
+                    .filter(({ isStatic, type }) => typehint || !isStatic || type !== TYPES.Signal)
                     .map(p => p.valueText)
                     .join(', ');
 

package/src/compiler/primitives.ts

@@ -5,68 +5,64 @@ import type { Bindings, IsReactiveCall } from './types';
 import scope from './bindings';
 
 
+// Something the compiler cannot lower; reported (every one of them) as a build error
+type Failure = { message: string; node: ts.Node };
+
 type PrimitivesTransformResult = {
     calls: ts.CallExpression[];
+    failures: Failure[];
     replacements: ReplacementIntent[];
 };
 
 type TransformContext = {
     bindings: Bindings;
     calls: ts.CallExpression[];
+    failures: Failure[];
     isReactiveCall: IsReactiveCall;
     replacements: ReplacementIntent[];
     tmpCounter: number;
 };
 
 
-// Pass 1: record every reactive() call and the variable each signal/computed is bound to, before
-// any reference is rewritten — a use that precedes its declaration in source order still resolves
+// Pass 1: lower every reactive() call. A signal or computed is only ever reached through the
+// variable it initializes (every read of that variable is rewritten), so anywhere else its signal
+// would leak unread and the call is rejected.
 function declare(ctx: TransformContext, node: ts.Node): void {
     if (ctx.isReactiveCall(node)) {
-        let call = node;
+        let call = node,
+            kind = scope.classify(ctx.bindings, call);
 
         ctx.calls.push(call);
 
-        if (call.arguments.length > 0) {
-            let arg = call.arguments[0],
-                classification: TYPES | null = TYPES.Signal;
-
-            if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) {
-                classification = TYPES.Computed;
-            }
-            else {
-                let unwrapped = arg;
-
-                while (ts.isAsExpression(unwrapped) || ts.isParenthesizedExpression(unwrapped) || ts.isTypeAssertion(unwrapped)) {
-                    unwrapped = unwrapped.expression;
-                }
-
-                if (ts.isArrayLiteralExpression(unwrapped) || ts.isObjectLiteralExpression(unwrapped)) {
-                    classification = null;
-                }
-                // Dynamic expression - use runtime reactive via namespace
-                else if (ts.isCallExpression(unwrapped) || ts.isIdentifier(unwrapped)) {
-                    classification = null;
-                    ctx.replacements.push({
-                        generate: () => `${NAMESPACE}.reactive`,
-                        node: call.expression
-                    });
-                }
+        if (kind === null) {
+            ctx.failures.push({
+                message: 'reactive() takes one argument whose kind (value, computed, array or object) is provable; ' +
+                    'pass a literal or give the argument a concrete type (not any, unknown or a mixed union)',
+                node: call
+            });
+        }
+        else if (kind === TYPES.Signal || kind === TYPES.Computed) {
+            if (!isBound(call)) {
+                ctx.failures.push({
+                    message: `a reactive ${kind === TYPES.Signal ? 'value' : 'computed'} must initialize a variable (or be a module's ` +
+                        'default export); anywhere else its signal is never read',
+                    node: call
+                });
             }
 
-            if (classification !== null) {
-                let target = targetOf(call),
-                    type = classification;
-
-                if (target) {
-                    scope.declare(ctx.bindings, target, type);
-                }
+            ctx.replacements.push({
+                generate: () => kind === TYPES.Computed ? `${NAMESPACE}.computed` : `${NAMESPACE}.signal`,
+                node: call.expression
+            });
+        }
+        else {
+            let arg = scope.unwrap(call.arguments[0]);
 
-                // Replace just the 'reactive' identifier with the appropriate namespace function
+            // Literals are lowered by the array and object transforms; any other array or object
+            // is built by the runtime constructor
+            if (!ts.isArrayLiteralExpression(arg) && !ts.isObjectLiteralExpression(arg)) {
                 ctx.replacements.push({
-                    generate: () => type === TYPES.Computed
-                        ? `${NAMESPACE}.computed`
-                        : `${NAMESPACE}.signal`,
+                    generate: () => `${NAMESPACE}.reactive`,
                     node: call.expression
                 });
             }
@@ -76,22 +72,51 @@ function declare(ctx: TransformContext, node: ts.Node): void {
     node.forEachChild(child => declare(ctx, child));
 }
 
-// A name slot rather than a value reference: a declaration's or member's own name, a property
-// name (`o.count`, `{ count: 1 }`, `{ count: local } = o`), or a label. A shorthand property's
-// name doubles as a read of the variable, so it is not a name slot. (TS 7's `isDeclarationName`
-// only tests the node kind, so it is true for every identifier and cannot be used here.)
-function isName(node: ts.Identifier, parent: ts.Node): boolean {
-    if (ts.isShorthandPropertyAssignment(parent)) {
+// `let x = reactive(...)`, `x = reactive(...)` or `export default reactive(...)`
+function isBound(call: ts.CallExpression): boolean {
+    let node: ts.Node = call,
+        parent = node.parent;
+
+    while (
+        parent &&
+        (ts.isAsExpression(parent) || ts.isNonNullExpression(parent) || ts.isParenthesizedExpression(parent) || ts.isSatisfiesExpression(parent))
+    ) {
+        node = parent;
+        parent = node.parent;
+    }
+
+    if (!parent) {
         return false;
     }
 
-    let slots = parent as { label?: ts.Node; name?: ts.Node; propertyName?: ts.Node };
+    if (ts.isVariableDeclaration(parent)) {
+        return parent.initializer === node && ts.isIdentifier(parent.name);
+    }
+
+    if (ts.isBinaryExpression(parent)) {
+        return parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.right === node && ts.isIdentifier(parent.left);
+    }
+
+    return ts.isExportAssignment(parent);
+}
+
+// A module namespace object: `import * as ns` (or an alias of it) or an `await import(...)`
+function isNamespace(bindings: Bindings, expression: ts.Expression): boolean {
+    let value = scope.unwrap(expression);
+
+    if (ts.isAwaitExpression(value)) {
+        value = scope.unwrap(value.expression);
+    }
+
+    if (ts.isCallExpression(value)) {
+        return value.expression.kind === ts.SyntaxKind.ImportKeyword;
+    }
 
-    return slots.name === node || slots.propertyName === node || slots.label === node;
+    return ts.isIdentifier(value) && scope.origin(bindings, value)?.declaration.kind === ts.SyntaxKind.SourceFile;
 }
 
 // Destructuring assignment targets (`({ count } = o)`, `[count] = xs`) write through a pattern
-// that has no per-signal rewrite, so they are left untouched
+// that has no per-signal rewrite
 function isPatternTarget(node: ts.Node): boolean {
     let current = node;
 
@@ -119,32 +144,42 @@ function isPatternTarget(node: ts.Node): boolean {
         ((ts.isForOfStatement(parent) || ts.isForInStatement(parent)) && parent.initializer === current);
 }
 
-function reference(ctx: TransformContext, node: ts.Identifier): void {
+// A binding read as `ns.count` / `ns['count']` is rewritten as a whole
+function readNode(identifier: ts.Node): ts.Expression {
+    let parent = identifier.parent!;
+
+    if (
+        (ts.isPropertyAccessExpression(parent) && parent.name === identifier) ||
+        (ts.isElementAccessExpression(parent) && parent.argumentExpression === identifier)
+    ) {
+        return parent;
+    }
+
+    return identifier as ts.Expression;
+}
+
+function reference(ctx: TransformContext, node: ts.Expression, kind: TYPES): void {
     let parent = node.parent;
 
-    if (!parent || ts.isExportSpecifier(parent) || ts.isImportSpecifier(parent) || isName(node, parent)) {
+    if (!parent) {
         return;
     }
 
-    let binding = scope.resolve(ctx.bindings, node);
-
-    if (!binding || binding.type === TYPES.Array) {
+    // `x = reactive(...)` replaces the signal itself
+    if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === node && ctx.isReactiveCall(scope.unwrap(parent.right))) {
         return;
     }
 
-    if (
-        (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === node && ctx.isReactiveCall(parent.right)) ||
-        (ts.isTypeOfExpression(parent) && parent.expression === node) ||
-        isPatternTarget(node)
-    ) {
+    if (isPatternTarget(node)) {
+        ctx.failures.push({ message: 'a reactive binding cannot be assigned through a destructuring pattern; assign it directly', node });
         return;
     }
 
-    let name = node.text;
+    let text = node.getText(ctx.bindings.sourceFile);
 
     if (ts.isShorthandPropertyAssignment(parent)) {
         ctx.replacements.push({
-            generate: () => `${name}: ${NAMESPACE}.read(${name})`,
+            generate: () => `${text}: ${NAMESPACE}.read(${text})`,
             node: parent
         });
 
@@ -173,14 +208,15 @@ function reference(ctx: TransformContext, node: ts.Identifier): void {
 
     if (!writeCtx) {
         ctx.replacements.push({
-            generate: () => `${NAMESPACE}.read(${name})`,
+            generate: () => `${NAMESPACE}.read(${text})`,
             node
         });
 
         return;
     }
 
-    if (binding.type === TYPES.Computed) {
+    if (kind === TYPES.Computed) {
+        ctx.failures.push({ message: 'a reactive computed is read-only', node });
         return;
     }
 
@@ -188,7 +224,7 @@ function reference(ctx: TransformContext, node: ts.Identifier): void {
         let right = parent.right;
 
         ctx.replacements.push({
-            generate: (sf) => `${NAMESPACE}.write(${name}, ${right.getText(sf)})`,
+            generate: (sf) => `${NAMESPACE}.write(${text}, ${right.getText(sf)})`,
             node: parent
         });
     }
@@ -197,7 +233,7 @@ function reference(ctx: TransformContext, node: ts.Identifier): void {
             right = parent.right;
 
         ctx.replacements.push({
-            generate: (sf) => `${NAMESPACE}.write(${name}, ${name}.value ${op} ${right.getText(sf)})`,
+            generate: (sf) => `${NAMESPACE}.write(${text}, ${text}.value ${op} ${right.getText(sf)})`,
             node: parent
         });
     }
@@ -207,13 +243,13 @@ function reference(ctx: TransformContext, node: ts.Identifier): void {
 
         if (ts.isExpressionStatement(unary.parent)) {
             ctx.replacements.push({
-                generate: () => `${NAMESPACE}.write(${name}, ${name}.value ${delta})`,
+                generate: () => `${NAMESPACE}.write(${text}, ${text}.value ${delta})`,
                 node: unary
             });
         }
         else if (ts.isPrefixUnaryExpression(unary)) {
             ctx.replacements.push({
-                generate: () => `(${NAMESPACE}.write(${name}, ${name}.value ${delta}), ${name}.value)`,
+                generate: () => `(${NAMESPACE}.write(${text}, ${text}.value ${delta}), ${text}.value)`,
                 node: unary
             });
         }
@@ -221,42 +257,55 @@ function reference(ctx: TransformContext, node: ts.Identifier): void {
             let tmp = `_t${ctx.tmpCounter++}`;
 
             ctx.replacements.push({
-                generate: () => `((${tmp}) => (${NAMESPACE}.write(${name}, ${tmp} ${delta}), ${tmp}))(${name}.value)`,
+                generate: () => `((${tmp}) => (${NAMESPACE}.write(${text}, ${tmp} ${delta}), ${tmp}))(${text}.value)`,
                 node: unary
             });
         }
     }
 }
 
-// Pass 2: rewrite reads and writes of every signal/computed binding. Type positions never read a
-// value, so they are not walked at all.
-function rewrite(ctx: TransformContext, node: ts.Node): void {
-    if (ts.isTypeNode(node)) {
-        return;
-    }
+// Pass 2: rewrite every read and write of a signal or computed binding, resolved by declaration so
+// a binding imported from another module (named, default, namespace, through a barrel) compiles
+// exactly like a local one. Destructuring one out of a module namespace would copy its signal.
+function rewrite(ctx: TransformContext): void {
+    let { bindings } = ctx;
 
-    if (ts.isIdentifier(node)) {
-        reference(ctx, node);
+    for (let [identifier, found] of bindings.origins) {
+        let kind = scope.kind(bindings, found);
 
-        return;
+        if (kind !== TYPES.Signal && kind !== TYPES.Computed) {
+            continue;
+        }
+
+        let parent = identifier.parent!;
+
+        if (ts.isBindingElement(parent) && parent.propertyName === identifier) {
+            ctx.failures.push({ message: 'a reactive binding cannot be destructured (it would copy its signal); read it through the namespace', node: identifier });
+            continue;
+        }
+
+        reference(ctx, readNode(identifier), kind);
     }
 
-    node.forEachChild(child => rewrite(ctx, child));
+    unpacked(ctx, bindings.sourceFile);
 }
 
-// The variable a reactive() call initializes: `let x = reactive(...)` or `x = reactive(...)`
-function targetOf(call: ts.CallExpression): ts.Identifier | null {
-    let parent = call.parent;
+// `const { count } = ns` names no property to resolve, so each element of a pattern destructuring
+// a module namespace is resolved as the export it copies
+function unpacked(ctx: TransformContext, node: ts.Node): void {
+    if (ts.isBindingElement(node) && !node.propertyName && ts.isObjectBindingPattern(node.parent)) {
+        let initializer = (node.parent.parent as { initializer?: ts.Expression }).initializer;
 
-    if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
-        return parent.name;
-    }
+        if (initializer && isNamespace(ctx.bindings, initializer)) {
+            let kind = scope.kind(ctx.bindings, scope.origin(ctx.bindings, node));
 
-    if (parent && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(parent.left)) {
-        return parent.left;
+            if (kind === TYPES.Signal || kind === TYPES.Computed) {
+                ctx.failures.push({ message: 'a reactive binding cannot be destructured (it would copy its signal); read it through the namespace', node });
+            }
+        }
     }
 
-    return null;
+    node.forEachChild(child => unpacked(ctx, child));
 }
 
 
@@ -264,13 +313,15 @@ export default (sourceFile: ts.SourceFile, bindings: Bindings, isReactiveCall: I
     let ctx: TransformContext = {
             bindings,
             calls: [],
+            failures: [],
             isReactiveCall,
             replacements: [],
             tmpCounter: 0
         };
 
     declare(ctx, sourceFile);
-    rewrite(ctx, sourceFile);
+    rewrite(ctx);
 
-    return { calls: ctx.calls, replacements: ctx.replacements };
+    return { calls: ctx.calls, failures: ctx.failures, replacements: ctx.replacements };
 };
+export type { Failure };

package/src/compiler/types.ts

@@ -1,12 +1,15 @@
 import type { ts } from '@esportsplus/typescript';
-import type { TYPES } from './constants';
+import type { Origin } from '@esportsplus/typescript/compiler';
 
 
+// What a file is compiled against: its values resolved to their declarations, and the
+// declarations `reactive` resolves to (one per installed copy of the package)
 type Bindings = {
     checker: ts.Checker;
-    names: Set<string>;
-    paths: Map<ts.Symbol, Set<string>>;
-    symbols: Map<ts.Symbol, TYPES>;
+    entries: Set<string>;
+    origins: Map<ts.Node, Origin>;
+    program: ts.Program;
+    sourceFile: ts.SourceFile;
 };
 
 type IsReactiveCall = (node: ts.Node) => node is ts.CallExpression;

package/src/types.ts

@@ -43,7 +43,8 @@ declare const READONLY: unique symbol;
 type Reactive<T> = T extends (...args: never[]) => infer R
     ? Settled<R> & { readonly [READONLY]: true }
     : T extends (infer U)[]
-        ? U[] & Pick<ReactiveArray<U>, 'clear' | 'dispose' | 'on' | 'once'>
+        // `$length` / `$set` are what the compiler lowers `.length` and element writes to
+        ? U[] & Pick<ReactiveArray<U>, '$length' | '$set' | 'clear' | 'dispose' | 'on' | 'once'>
         : T extends Record<PropertyKey, unknown>
             ? { [K in keyof T]: T[K] extends (infer U)[] ? Reactive<U[]> : T[K]; } & { dispose: VoidFunction }
             : T;