@fulcro/transform-core 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -18,4 +18,5 @@
  */
 export { createFileTransformer, type FileTransformer, type TransformCoreOptions, } from './program/index.js';
 export { type CallForm, type CallRewriter, IDENTIFIER_PATTERN, isOwnedCall, isTupleType, type RewriteContext, utilityModuleSegment, } from './shared/index.js';
+export { buildStructuralTest, type StructuralOptions, type TypeTest, } from './structural/index.js';
 export { createTransformer, type TransformerFactory, type TransformerOptions, } from './transformer/index.js';

package/dist/index.js

@@ -18,7 +18,7 @@
  * other.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTransformer = exports.utilityModuleSegment = exports.isTupleType = exports.isOwnedCall = exports.IDENTIFIER_PATTERN = exports.createFileTransformer = void 0;
+exports.createTransformer = exports.buildStructuralTest = exports.utilityModuleSegment = exports.isTupleType = exports.isOwnedCall = exports.IDENTIFIER_PATTERN = exports.createFileTransformer = void 0;
 var program_1 = require("./program/index.js");
 Object.defineProperty(exports, "createFileTransformer", { enumerable: true, get: function () { return program_1.createFileTransformer; } });
 var shared_1 = require("./shared/index.js");
@@ -26,5 +26,7 @@ Object.defineProperty(exports, "IDENTIFIER_PATTERN", { enumerable: true, get: fu
 Object.defineProperty(exports, "isOwnedCall", { enumerable: true, get: function () { return shared_1.isOwnedCall; } });
 Object.defineProperty(exports, "isTupleType", { enumerable: true, get: function () { return shared_1.isTupleType; } });
 Object.defineProperty(exports, "utilityModuleSegment", { enumerable: true, get: function () { return shared_1.utilityModuleSegment; } });
+var structural_1 = require("./structural/index.js");
+Object.defineProperty(exports, "buildStructuralTest", { enumerable: true, get: function () { return structural_1.buildStructuralTest; } });
 var transformer_1 = require("./transformer/index.js");
 Object.defineProperty(exports, "createTransformer", { enumerable: true, get: function () { return transformer_1.createTransformer; } });

package/dist/structural/explain/index.d.ts

@@ -0,0 +1,14 @@
+import typescript from 'typescript';
+/**
+ * Builds the walker that names where a value stopped matching a type.
+ *
+ * @param type Type the call asked for.
+ * @param written The type as the consumer wrote it.
+ * @param at Node the call sits at, for scope.
+ * @param checker Checker of the program being compiled.
+ * @param factory Node factory of the current transformation.
+ * @param fallback Builds the yes-or-no check for a type, for what this cannot
+ * describe precisely.
+ * @returns The arrow function, or `null` when nothing useful can be said.
+ */
+export declare const buildExplainer: (type: typescript.Type, written: string, at: typescript.Node, checker: typescript.TypeChecker, factory: typescript.NodeFactory, fallback: (type: typescript.Type, value: typescript.Expression) => typescript.Expression | null) => typescript.Expression | null;

package/dist/structural/explain/index.js

@@ -0,0 +1,287 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExplainer = void 0;
+const typescript_1 = __importDefault(require("typescript"));
+/**
+ * Writing out *where* a value stopped matching a type.
+ *
+ * The check beside this one answers yes or no, which is all a filter needs. An
+ * `as<Order>(payload)` that refuses needs more than that: told only "not an
+ * Order" about a record with forty fields, you are no better off than before
+ * the check existed.
+ *
+ * So this emits a second walker that returns the first path that failed, and
+ * what was there instead:
+ *
+ * ```text
+ * customer.email: expected string, got number
+ * items[3].quantity: expected number, got undefined
+ * ```
+ *
+ * It runs **only after the fast check has already refused**, so nothing on the
+ * happy path pays for it. That is also why it can be written the slow, obvious
+ * way — as statements that walk and return early — rather than as one fused
+ * expression.
+ *
+ * Where a type is more than this can describe precisely — an intersection, a
+ * tuple, a union of object shapes — it falls back to naming the type that was
+ * expected at that path. Vague beats wrong: a path is a promise about where the
+ * problem is, and inventing one would send someone to the wrong field.
+ */
+/** How deep the walker descends before falling back to naming the type. */
+const MAX_DEPTH = 8;
+/**
+ * Tells whether a flag is present on a type.
+ *
+ * @param type Type being inspected.
+ * @param flag Flag looked for.
+ * @returns `true` when the type carries it.
+ */
+const has = (type, flag) => (type.flags & flag) !== 0;
+/**
+ * Builds the expression naming what a value actually is, at runtime.
+ *
+ * `typeof` with `null` corrected, which is the one answer it gives that would
+ * mislead someone reading the message.
+ *
+ * @param factory Node factory.
+ * @param value Expression being described.
+ * @returns An expression producing the description.
+ */
+const describe = (factory, value) => factory.createConditionalExpression(factory.createStrictEquality(value, factory.createNull()), undefined, factory.createStringLiteral('null'), undefined, factory.createTypeOfExpression(value));
+/**
+ * Builds `return "<path>: expected <expected>, got " + typeof value`.
+ *
+ * @param factory Node factory.
+ * @param path Path of the value inside the whole, as an expression so that an
+ * array index can be part of it.
+ * @param expected Name of the type that was wanted.
+ * @param value Expression that failed.
+ * @returns The return statement.
+ */
+const complain = (factory, path, expected, value) => {
+    // At the root there is no path to name, and prefixing an empty one leaves a
+    // stray colon in front of the message.
+    const atRoot = typescript_1.default.isStringLiteral(path) && path.text === '';
+    const prefix = atRoot
+        ? factory.createStringLiteral(`expected ${expected}, got `)
+        : factory.createAdd(path, factory.createStringLiteral(`: expected ${expected}, got `));
+    return factory.createReturnStatement(factory.createAdd(prefix, describe(factory, value)));
+};
+/**
+ * Reads a property off an expression, quoting the key when it has to.
+ *
+ * @param factory Node factory.
+ * @param value Expression carrying the property.
+ * @param name Name of the property.
+ * @returns The access expression.
+ */
+const propertyOf = (factory, value, name) => /^[A-Za-z_$][\w$]*$/.test(name)
+    ? factory.createPropertyAccessExpression(value, name)
+    : factory.createElementAccessExpression(value, factory.createStringLiteral(name));
+/**
+ * Extends a path expression with a property name.
+ *
+ * @param factory Node factory.
+ * @param path Path so far.
+ * @param name Property being descended into.
+ * @returns The extended path.
+ */
+const pathTo = (factory, path, name) => typescript_1.default.isStringLiteral(path) && path.text === ''
+    ? factory.createStringLiteral(name)
+    : factory.createAdd(path, factory.createStringLiteral(`.${name}`));
+/**
+ * Writes the statements that look for a failure of one type at one path.
+ *
+ * @param type Type being checked for.
+ * @param value Expression the check applies to.
+ * @param path Path of that expression inside the whole.
+ * @param written The type as the consumer wrote it.
+ * @param walk State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns Statements returning a description, or `null` when nothing can be
+ * said precisely enough to be worth saying.
+ */
+const explainFor = (type, value, path, written, walk, depth) => {
+    const { checker, factory } = walk;
+    if (depth > MAX_DEPTH)
+        return vague(type, value, path, written, walk);
+    // Nothing to report: these accept anything.
+    if (has(type, typescript_1.default.TypeFlags.Any | typescript_1.default.TypeFlags.Unknown)) {
+        return [];
+    }
+    const primitive = primitiveNameOf(type);
+    if (primitive !== null) {
+        return [
+            factory.createIfStatement(factory.createStrictInequality(factory.createTypeOfExpression(value), factory.createStringLiteral(primitive)), factory.createBlock([complain(factory, path, primitive, value)], true)),
+        ];
+    }
+    if (has(type, typescript_1.default.TypeFlags.Object)) {
+        if (checker.isArrayType(type)) {
+            return explainArray(type, value, path, written, walk, depth);
+        }
+        // A tuple, a function, a class: all described by name rather than walked.
+        // A class is checked with `instanceof` and there is no sub-path to point
+        // at; a tuple would need its own index handling for little gain.
+        if (checker.isTupleType(type)) {
+            return vague(type, value, path, written, walk);
+        }
+        const symbol = type.getSymbol();
+        if (symbol !== undefined &&
+            (symbol.flags & typescript_1.default.SymbolFlags.Class) !== 0) {
+            return vague(type, value, path, written, walk);
+        }
+        if (type.getCallSignatures().length > 0) {
+            return vague(type, value, path, written, walk);
+        }
+        return explainObject(type, value, path, written, walk, depth);
+    }
+    // Unions, intersections, literals and everything else: the yes-or-no check
+    // is exact, so it decides, and the message names the type rather than
+    // guessing at which member was meant.
+    return vague(type, value, path, written, walk);
+};
+/**
+ * The primitive flags that have a `typeof` name, and that name.
+ */
+const PRIMITIVE_NAMES = [
+    [typescript_1.default.TypeFlags.StringLike, 'string'],
+    [typescript_1.default.TypeFlags.NumberLike, 'number'],
+    [typescript_1.default.TypeFlags.BigIntLike, 'bigint'],
+    [typescript_1.default.TypeFlags.BooleanLike, 'boolean'],
+    [typescript_1.default.TypeFlags.ESSymbolLike, 'symbol'],
+];
+/**
+ * Names the `typeof` group a type belongs to, when it belongs to one.
+ *
+ * Literal types are excluded on purpose: `'dark'` is a string as far as
+ * `typeof` goes, and reporting it as one would be a description that passes
+ * while the value is still wrong.
+ *
+ * @param type Type being classified.
+ * @returns The `typeof` name, or `null`.
+ */
+const primitiveNameOf = (type) => {
+    if (type.isLiteral() || has(type, typescript_1.default.TypeFlags.BooleanLiteral)) {
+        return null;
+    }
+    if (type.isUnion())
+        return null;
+    for (const [flag, name] of PRIMITIVE_NAMES) {
+        if (has(type, flag))
+            return name;
+    }
+    return null;
+};
+/**
+ * Falls back to naming the expected type at a path.
+ *
+ * @param type Type that was wanted.
+ * @param value Expression that failed.
+ * @param path Path of that expression.
+ * @param written The type as written.
+ * @param walk State of the generation.
+ * @returns The statements, or `null` when even the yes-or-no check is missing.
+ */
+const vague = (type, value, path, written, walk) => {
+    const check = walk.fallback(type, value);
+    if (check === null)
+        return null;
+    return [
+        walk.factory.createIfStatement(walk.factory.createPrefixUnaryExpression(typescript_1.default.SyntaxKind.ExclamationToken, walk.factory.createParenthesizedExpression(check)), walk.factory.createBlock([complain(walk.factory, path, written, value)], true)),
+    ];
+};
+/**
+ * Writes the statements describing an array that does not match.
+ *
+ * @param type Array type being checked for.
+ * @param value Expression the check applies to.
+ * @param path Path of that expression.
+ * @param written The type as written.
+ * @param walk State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns The statements, or `null`.
+ */
+const explainArray = (type, value, path, written, walk, depth) => {
+    const { checker, factory } = walk;
+    const [element] = checker.getTypeArguments(type);
+    if (element === undefined)
+        return vague(type, value, path, written, walk);
+    const isArray = factory.createIfStatement(factory.createPrefixUnaryExpression(typescript_1.default.SyntaxKind.ExclamationToken, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier('Array'), 'isArray'), undefined, [value])), factory.createBlock([complain(factory, path, 'an array', value)], true));
+    const index = `i${walk.counter.value++}`;
+    const elementPath = factory.createAdd(factory.createAdd(path, factory.createStringLiteral('[')), factory.createAdd(factory.createIdentifier(index), factory.createStringLiteral(']')));
+    const inner = explainFor(element, factory.createElementAccessExpression(value, factory.createIdentifier(index)), elementPath, checker.typeToString(element), walk, depth + 1);
+    if (inner === null)
+        return [isArray];
+    // A plain loop rather than `every`, so the index is in hand for the path and
+    // the walk can return out of the middle of it.
+    return [
+        isArray,
+        factory.createForStatement(factory.createVariableDeclarationList([
+            factory.createVariableDeclaration(index, undefined, undefined, factory.createNumericLiteral(0)),
+        ], typescript_1.default.NodeFlags.Let), factory.createLessThan(factory.createIdentifier(index), factory.createPropertyAccessExpression(value, 'length')), factory.createPostfixIncrement(factory.createIdentifier(index)), factory.createBlock(inner, true)),
+    ];
+};
+/**
+ * Writes the statements describing an object that does not match.
+ *
+ * @param type Object type being checked for.
+ * @param value Expression the check applies to.
+ * @param path Path of that expression.
+ * @param written The type as written.
+ * @param walk State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns The statements, or `null`.
+ */
+const explainObject = (type, value, path, written, walk, depth) => {
+    const { checker, factory } = walk;
+    const properties = type.getProperties();
+    if (properties.length === 0)
+        return vague(type, value, path, written, walk);
+    // Ruled out before any property is read, or the walk would throw while
+    // trying to explain rather than returning the explanation.
+    const statements = [
+        factory.createIfStatement(factory.createLogicalOr(factory.createStrictEquality(value, factory.createNull()), factory.createStrictInequality(factory.createTypeOfExpression(value), factory.createStringLiteral('object'))), factory.createBlock([complain(factory, path, written, value)], true)),
+    ];
+    for (const property of properties) {
+        const name = property.getName();
+        if (name.startsWith('__@'))
+            continue;
+        const propertyType = checker.getTypeOfSymbolAtLocation(property, walk.at);
+        const access = propertyOf(factory, value, name);
+        const inner = explainFor(propertyType, access, pathTo(factory, path, name), checker.typeToString(propertyType), walk, depth + 1);
+        if (inner === null || inner.length === 0)
+            continue;
+        const optional = (property.flags & typescript_1.default.SymbolFlags.Optional) !== 0;
+        // An absent optional property is not a failure, so the whole check for it
+        // is skipped rather than being made to pass.
+        statements.push(optional
+            ? factory.createIfStatement(factory.createStrictInequality(access, factory.createIdentifier('undefined')), factory.createBlock(inner, true))
+            : factory.createBlock(inner, true));
+    }
+    return statements;
+};
+/**
+ * Builds the walker that names where a value stopped matching a type.
+ *
+ * @param type Type the call asked for.
+ * @param written The type as the consumer wrote it.
+ * @param at Node the call sits at, for scope.
+ * @param checker Checker of the program being compiled.
+ * @param factory Node factory of the current transformation.
+ * @param fallback Builds the yes-or-no check for a type, for what this cannot
+ * describe precisely.
+ * @returns The arrow function, or `null` when nothing useful can be said.
+ */
+const buildExplainer = (type, written, at, checker, factory, fallback) => {
+    const walk = { checker, factory, at, fallback, counter: { value: 0 } };
+    const parameter = 'v';
+    const body = explainFor(type, factory.createIdentifier(parameter), factory.createStringLiteral(''), written, walk, 0);
+    if (body === null || body.length === 0)
+        return null;
+    return factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, parameter)], undefined, factory.createToken(typescript_1.default.SyntaxKind.EqualsGreaterThanToken), factory.createBlock([...body, factory.createReturnStatement(factory.createNull())], true));
+};
+exports.buildExplainer = buildExplainer;

package/dist/structural/index.d.ts

@@ -0,0 +1,88 @@
+import typescript from 'typescript';
+import { RewriteContext } from '../shared/index.js';
+/**
+ * Writing out the checks a type implies.
+ *
+ * A type with no single runtime token — an interface, an object literal type, a
+ * union of them — still has a *shape*, and the checker knows it completely
+ * while the compiler is running. So rather than looking for something to point
+ * at, this writes the test out: the properties, their types, their optionality,
+ * all the way down.
+ *
+ * ```ts
+ * // interface Account { id: number; tags: string[] }
+ * values.ofType<Account>();
+ *
+ * // becomes, near enough:
+ * values.ofType({
+ * 	name: 'Account',
+ * 	matches: (v) =>
+ * 		v !== null &&
+ * 		typeof v === 'object' &&
+ * 		typeof v.id === 'number' &&
+ * 		Array.isArray(v.tags) &&
+ * 		v.tags.every((e) => typeof e === 'string'),
+ * });
+ * ```
+ *
+ * **The governing rule is that it refuses whatever it cannot prove.** A test
+ * that answers `true` for something that is not an `Account` is worse than no
+ * test at all: it is false confidence at exactly the boundary where the data is
+ * least trustworthy. So every construct this does not fully understand returns
+ * `null` from here, and the call is left unresolved for the runtime to reject
+ * out loud. There is no partial or optimistic check anywhere in this file.
+ */
+/**
+ * A test deciding whether a value is of some type, by looking at its shape.
+ *
+ * What this module emits, and what the runtime halves of `ofType`, `cast`, `is`
+ * and `as` receive. Declared here because more than one library consumes it;
+ * each also re-exports a structurally identical one of its own, so nothing a
+ * consumer imports depends on this package.
+ *
+ * @template R Type a passing value is taken to be.
+ */
+export interface TypeTest<R> {
+    /**
+     * Decides whether a value is an `R`.
+     *
+     * @param value Value being tested.
+     * @returns `true` when the value is of that type.
+     */
+    readonly matches: (value: unknown) => boolean;
+    /**
+     * Names where a value stopped being an `R`.
+     *
+     * Emitted only where the answer is worth the code — a failing `as<T>()`
+     * needs to say which field was wrong, while a filter only needs yes or no.
+     * Runs after `matches` has already refused, so the happy path never pays
+     * for it.
+     *
+     * @param value Value that failed.
+     * @returns The path and reason, or `null` if it cannot say.
+     */
+    readonly explain?: (value: unknown) => string | null;
+    /** Name of the type, as it was written. */
+    readonly name?: string;
+}
+/** What a caller wants emitted beyond the yes-or-no check. */
+export interface StructuralOptions {
+    /**
+     * Also emit a walker naming where a value stopped matching.
+     *
+     * Worth it where a refusal has to be actionable — a failing `as<T>()` — and
+     * not where the answer is only ever used as a filter.
+     */
+    readonly explain?: boolean;
+}
+/**
+ * Builds the shape test for a type, when one can be proven.
+ *
+ * @param type Type the call asked for.
+ * @param written The type as the consumer wrote it, for error messages.
+ * @param at Node the call sits at, for scope.
+ * @param context Compilation in progress.
+ * @returns The object literal to pass at runtime, or `null` when the type
+ * cannot be checked honestly.
+ */
+export declare const buildStructuralTest: (type: typescript.Type, written: string, at: typescript.Node, context: RewriteContext, options?: StructuralOptions) => typescript.Expression | null;

package/dist/structural/index.js

@@ -0,0 +1,498 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStructuralTest = void 0;
+const typescript_1 = __importDefault(require("typescript"));
+const explain_1 = require("./explain/index.js");
+/** How deep a type may nest before this gives up rather than grinding on. */
+const MAX_DEPTH = 12;
+/**
+ * Tells whether a flag is present on a type.
+ *
+ * @param type Type being inspected.
+ * @param flag Flag looked for.
+ * @returns `true` when the type carries it.
+ */
+const has = (type, flag) => (type.flags & flag) !== 0;
+/**
+ * Builds `typeof value === name`.
+ *
+ * @param factory Node factory.
+ * @param value Expression being tested.
+ * @param name Expected `typeof` answer.
+ * @returns The comparison.
+ */
+const typeofIs = (factory, value, name) => factory.createStrictEquality(factory.createTypeOfExpression(value), factory.createStringLiteral(name));
+/**
+ * Joins checks with `&&`, or answers `true` when there are none.
+ *
+ * @param factory Node factory.
+ * @param checks Checks to combine.
+ * @returns The combined expression.
+ */
+const all = (factory, checks) => checks.length === 0
+    ? factory.createTrue()
+    : checks.reduce((left, right) => factory.createLogicalAnd(left, right));
+/**
+ * Joins checks with `||`, or answers `false` when there are none.
+ *
+ * @param factory Node factory.
+ * @param checks Checks to combine.
+ * @returns The combined expression.
+ */
+const any = (factory, checks) => checks.length === 0
+    ? factory.createFalse()
+    : checks.reduce((left, right) => factory.createLogicalOr(left, right));
+/**
+ * Reads a property off an expression, quoting the key when it has to.
+ *
+ * @param factory Node factory.
+ * @param value Expression carrying the property.
+ * @param name Name of the property.
+ * @returns The access expression.
+ */
+const propertyOf = (factory, value, name) => /^[A-Za-z_$][\w$]*$/.test(name)
+    ? factory.createPropertyAccessExpression(value, name)
+    : factory.createElementAccessExpression(value, factory.createStringLiteral(name));
+/**
+ * Names a global constructor that is safe to test with `instanceof`.
+ *
+ * Only the ones every runtime has. A user class goes through the scope check
+ * instead, since it may not be in scope as a value at the call site.
+ */
+const GLOBAL_CLASSES = new Set([
+    'Date',
+    'RegExp',
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    'Promise',
+    'Error',
+    'ArrayBuffer',
+    'DataView',
+    'Uint8Array',
+    'Int8Array',
+    'Uint16Array',
+    'Int16Array',
+    'Uint32Array',
+    'Int32Array',
+    'Float32Array',
+    'Float64Array',
+    'BigInt64Array',
+    'BigUint64Array',
+]);
+/**
+ * Tells whether a type already admits `undefined` on its own.
+ *
+ * An optional property normally carries it in its declared type, and the check
+ * written for that union tests it. Knowing that saves wrapping the result in
+ * the same test a second time.
+ *
+ * @param type Type being inspected.
+ * @returns `true` when `undefined` is one of its members.
+ */
+const admitsUndefined = (type) => has(type, typescript_1.default.TypeFlags.Undefined) ||
+    (type.isUnion() &&
+        type.types.some((member) => has(member, typescript_1.default.TypeFlags.Undefined)));
+/**
+ * Lists the types a type is built out of, for the cycle search.
+ *
+ * Deliberately stops where the writer stops: a class is tested with
+ * `instanceof` and a function by `typeof`, so neither is descended into and
+ * neither can put a type in a cycle it does not really have.
+ *
+ * @param type Type being taken apart.
+ * @param checker Checker of the program being compiled.
+ * @param at Node the lookups happen from.
+ * @returns The types it refers to.
+ */
+const partsOf = (type, checker, at) => {
+    if (type.isUnionOrIntersection())
+        return type.types;
+    if (!has(type, typescript_1.default.TypeFlags.Object))
+        return [];
+    if (checker.isArrayType(type) || checker.isTupleType(type)) {
+        return checker.getTypeArguments(type);
+    }
+    const symbol = type.getSymbol();
+    if (symbol !== undefined &&
+        ((symbol.flags & typescript_1.default.SymbolFlags.Class) !== 0 ||
+            GLOBAL_CLASSES.has(symbol.getName()))) {
+        return [];
+    }
+    if (type.getCallSignatures().length > 0 ||
+        type.getConstructSignatures().length > 0) {
+        return [];
+    }
+    return type
+        .getProperties()
+        .map((property) => checker.getTypeOfSymbolAtLocation(property, at));
+};
+/**
+ * Finds the types that take part in a cycle.
+ *
+ * Run before a single node is built, because whether a type needs to become a
+ * function is a property of the whole graph and cannot be decided from inside
+ * a depth-first walk of it: by the time a cycle is met, the type that closes it
+ * has already been written out inline.
+ *
+ * @param root Type the call asked for.
+ * @param checker Checker of the program being compiled.
+ * @param at Node the lookups happen from.
+ * @returns Every type that refers back to itself, directly or through others.
+ */
+const findRecursive = (root, checker, at) => {
+    const recursive = new Set();
+    const finished = new Set();
+    const path = new Set();
+    const visit = (type) => {
+        // Met again on the way down: this is the type the cycle closes on.
+        if (path.has(type)) {
+            recursive.add(type);
+            return;
+        }
+        if (finished.has(type))
+            return;
+        path.add(type);
+        for (const part of partsOf(type, checker, at))
+            visit(part);
+        path.delete(type);
+        finished.add(type);
+    };
+    visit(root);
+    return recursive;
+};
+/**
+ * Tells whether a name is usable as a value where the call sits.
+ *
+ * A class imported with `import type` is erased before the emitted code runs,
+ * so naming it in a runtime position would compile and then fail.
+ *
+ * @param name Name being looked up.
+ * @param generation State of the generation.
+ * @returns `true` when the name survives into the emitted code as a value.
+ */
+const isValueInScope = (name, generation) => {
+    if (GLOBAL_CLASSES.has(name))
+        return true;
+    const resolved = generation.context.checker.resolveName(name, generation.at, typescript_1.default.SymbolFlags.Value, false);
+    if (resolved === undefined)
+        return false;
+    return !(resolved.declarations ?? []).some((declaration) => {
+        if (typescript_1.default.isImportSpecifier(declaration)) {
+            return (declaration.isTypeOnly || declaration.parent.parent.isTypeOnly === true);
+        }
+        if (typescript_1.default.isImportClause(declaration))
+            return declaration.isTypeOnly;
+        return false;
+    });
+};
+/**
+ * Writes the check for one type, applied to one expression.
+ *
+ * @param type Type being checked for.
+ * @param value Expression the check is applied to.
+ * @param generation State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns The check, or `null` when the type cannot be proven at runtime.
+ */
+const checkFor = (type, value, generation, depth) => {
+    const { checker, factory } = generation.context;
+    if (depth > MAX_DEPTH)
+        return null;
+    // Accepts everything, honestly: there is nothing to check, and saying so is
+    // not the same as failing to check.
+    if (has(type, typescript_1.default.TypeFlags.Any | typescript_1.default.TypeFlags.Unknown)) {
+        return factory.createTrue();
+    }
+    if (has(type, typescript_1.default.TypeFlags.Never))
+        return factory.createFalse();
+    if (has(type, typescript_1.default.TypeFlags.Null)) {
+        return factory.createStrictEquality(value, factory.createNull());
+    }
+    if (has(type, typescript_1.default.TypeFlags.Undefined | typescript_1.default.TypeFlags.Void)) {
+        return factory.createStrictEquality(value, factory.createIdentifier('undefined'));
+    }
+    // Literals before the primitive groups they belong to, or `'dark'` would be
+    // checked as any old string.
+    if (type.isStringLiteral()) {
+        return factory.createStrictEquality(value, factory.createStringLiteral(type.value));
+    }
+    if (type.isNumberLiteral()) {
+        return factory.createStrictEquality(value, factory.createNumericLiteral(type.value));
+    }
+    if (has(type, typescript_1.default.TypeFlags.BooleanLiteral)) {
+        const written = checker.typeToString(type);
+        return factory.createStrictEquality(value, written === 'true' ? factory.createTrue() : factory.createFalse());
+    }
+    // A union takes in enums too, which the checker presents as one.
+    if (type.isUnion()) {
+        const members = type.types.map((member) => checkFor(member, value, generation, depth + 1));
+        if (members.some((member) => member === null))
+            return null;
+        return factory.createParenthesizedExpression(any(factory, members));
+    }
+    if (type.isIntersection()) {
+        const members = type.types.map((member) => checkFor(member, value, generation, depth + 1));
+        if (members.some((member) => member === null))
+            return null;
+        return factory.createParenthesizedExpression(all(factory, members));
+    }
+    if (has(type, typescript_1.default.TypeFlags.StringLike)) {
+        return typeofIs(factory, value, 'string');
+    }
+    if (has(type, typescript_1.default.TypeFlags.NumberLike)) {
+        return typeofIs(factory, value, 'number');
+    }
+    if (has(type, typescript_1.default.TypeFlags.BigIntLike)) {
+        return typeofIs(factory, value, 'bigint');
+    }
+    if (has(type, typescript_1.default.TypeFlags.BooleanLike)) {
+        return typeofIs(factory, value, 'boolean');
+    }
+    if (has(type, typescript_1.default.TypeFlags.ESSymbolLike)) {
+        return typeofIs(factory, value, 'symbol');
+    }
+    if (!has(type, typescript_1.default.TypeFlags.Object))
+        return null;
+    // A type that refers back to itself. It becomes a function so that the
+    // reference has a name to call, and every mention of it — the first one
+    // included — becomes a call to that name.
+    if (generation.recursive.has(type)) {
+        return checkThroughFunction(type, value, generation, depth);
+    }
+    // Belt and braces. The cycle search above should have caught anything that
+    // could re-enter, so reaching here means it missed one, and writing it out
+    // would not terminate.
+    if (generation.open.has(type))
+        return null;
+    return checkForObject(type, value, generation, depth);
+};
+/**
+ * Writes a recursive type as a named function, and refers to it by name.
+ *
+ * The name is registered **before** the body is written, which is the whole
+ * trick: the reference that closes the cycle is met while the body is still
+ * being built, and it needs something to call.
+ *
+ * @param type Type being checked for.
+ * @param value Expression the check is applied to.
+ * @param generation State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns A call to the function, or `null` when the body cannot be written.
+ */
+const checkThroughFunction = (type, value, generation, depth) => {
+    const { factory } = generation.context;
+    const existing = generation.declared.get(type);
+    if (existing !== undefined) {
+        return factory.createCallExpression(factory.createIdentifier(existing.name), undefined, [value]);
+    }
+    const declaration = {
+        name: `check${generation.counter.value++}`,
+    };
+    generation.declared.set(type, declaration);
+    // Written against its own parameter rather than against the caller's
+    // expression, because the same body serves every call site.
+    const parameter = `r${generation.counter.value++}`;
+    const body = checkForObject(type, factory.createIdentifier(parameter), generation, 
+    // Reset: the depth cap is there to stop an unbounded walk, and a
+    // recursive type is bounded by the function call rather than by how deep
+    // the writer went to reach it.
+    0);
+    if (body === null) {
+        // Nothing can be emitted, so the half-registered name must go with it.
+        generation.declared.delete(type);
+        return null;
+    }
+    declaration.body = factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, parameter)], undefined, factory.createToken(typescript_1.default.SyntaxKind.EqualsGreaterThanToken), body);
+    return factory.createCallExpression(factory.createIdentifier(declaration.name), undefined, [value]);
+};
+/**
+ * Writes the check for an object type: array, tuple, class, or plain shape.
+ *
+ * @param type Type being checked for.
+ * @param value Expression the check is applied to.
+ * @param generation State of the generation.
+ * @param depth How deep into the type this is.
+ * @returns The check, or `null` when the type cannot be proven at runtime.
+ */
+const checkForObject = (type, value, generation, depth) => {
+    const { checker, factory } = generation.context;
+    generation.open.add(type);
+    try {
+        if (checker.isArrayType(type)) {
+            const [element] = checker.getTypeArguments(type);
+            if (element === undefined)
+                return null;
+            const parameter = `e${generation.counter.value++}`;
+            const inner = checkFor(element, factory.createIdentifier(parameter), generation, depth + 1);
+            if (inner === null)
+                return null;
+            // Every element, not a sample: a check that looked at the first one
+            // would be exactly the optimistic half-answer this file refuses to
+            // produce. What that costs is the caller's to know, and documented.
+            return factory.createLogicalAnd(factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier('Array'), 'isArray'), undefined, [value]), factory.createCallExpression(factory.createPropertyAccessExpression(value, 'every'), undefined, [
+                factory.createArrowFunction(undefined, undefined, [
+                    factory.createParameterDeclaration(undefined, undefined, parameter),
+                ], undefined, factory.createToken(typescript_1.default.SyntaxKind.EqualsGreaterThanToken), inner),
+            ]));
+        }
+        if (checker.isTupleType(type)) {
+            const reference = type;
+            const target = reference.target;
+            // A rest or optional element makes the length variable, and a length
+            // this cannot pin down is one it will not guess at.
+            if (target.hasRestElement || target.minLength !== target.fixedLength) {
+                return null;
+            }
+            const elements = checker.getTypeArguments(reference);
+            const checks = [
+                factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier('Array'), 'isArray'), undefined, [value]),
+                factory.createStrictEquality(factory.createPropertyAccessExpression(value, 'length'), factory.createNumericLiteral(elements.length)),
+            ];
+            for (const [index, element] of elements.entries()) {
+                const inner = checkFor(element, factory.createElementAccessExpression(value, factory.createNumericLiteral(index)), generation, depth + 1);
+                if (inner === null)
+                    return null;
+                checks.push(inner);
+            }
+            return factory.createParenthesizedExpression(all(factory, checks));
+        }
+        const symbol = type.getSymbol();
+        // A class, or one of the built-in types that behaves like one.
+        //
+        // The built-ins do not carry `SymbolFlags.Class`: the standard library
+        // declares `interface Date` beside a separate `declare var Date`, so the
+        // flag check alone misses them — and then the shape path below writes out
+        // a `typeof` check for all fifty methods of `Date`, including its symbol
+        // keyed member, which cannot be named in source at all. Matching the
+        // known names first is what keeps that from being emitted.
+        const isClassLike = symbol !== undefined &&
+            ((symbol.flags & typescript_1.default.SymbolFlags.Class) !== 0 ||
+                GLOBAL_CLASSES.has(symbol.getName()));
+        if (isClassLike && symbol !== undefined) {
+            const name = symbol.getName();
+            return isValueInScope(name, generation)
+                ? factory.createBinaryExpression(value, factory.createToken(typescript_1.default.SyntaxKind.InstanceOfKeyword), factory.createIdentifier(name))
+                : null;
+        }
+        // A function type. Only that it is callable can be checked — no runtime
+        // sees a signature — and the shape below would be wrong for one.
+        if (type.getCallSignatures().length > 0 ||
+            type.getConstructSignatures().length > 0) {
+            return typeofIs(factory, value, 'function');
+        }
+        // An index signature means arbitrary keys, which this does not attempt.
+        if (checker.getIndexInfosOfType(type).length > 0)
+            return null;
+        const properties = type.getProperties();
+        // An object type with nothing in it accepts any object, and a check that
+        // only says "is an object" is not what the caller asked about.
+        if (properties.length === 0)
+            return null;
+        const checks = [
+            factory.createStrictInequality(value, factory.createNull()),
+            typeofIs(factory, value, 'object'),
+        ];
+        for (const property of properties) {
+            const name = property.getName();
+            // A member keyed by a symbol. The compiler spells these `__@name@id`,
+            // which is not a property name any source can write, so there is no
+            // honest check to emit for one.
+            if (name.startsWith('__@'))
+                return null;
+            const propertyType = checker.getTypeOfSymbolAtLocation(property, generation.at);
+            const optional = (property.flags & typescript_1.default.SymbolFlags.Optional) !== 0;
+            const access = propertyOf(factory, value, name);
+            const inner = checkFor(propertyType, access, generation, depth + 1);
+            if (inner === null)
+                return null;
+            // Absent and present-but-undefined are the same here, which is what
+            // reading a missing property gives back anyway. Extra properties are
+            // never rejected: structural typing allows them, and rejecting them
+            // would make this disagree with the compiler that produced it.
+            //
+            // Only wrapped when the property's own type does not already admit
+            // `undefined`, which it normally does — otherwise the emitted check
+            // asks the same question twice.
+            const needsWrapping = optional && !admitsUndefined(propertyType);
+            checks.push(needsWrapping
+                ? factory.createParenthesizedExpression(factory.createLogicalOr(factory.createStrictEquality(access, factory.createIdentifier('undefined')), inner))
+                : inner);
+        }
+        return factory.createParenthesizedExpression(all(factory, checks));
+    }
+    finally {
+        generation.open.delete(type);
+    }
+};
+/**
+ * Builds the shape test for a type, when one can be proven.
+ *
+ * @param type Type the call asked for.
+ * @param written The type as the consumer wrote it, for error messages.
+ * @param at Node the call sits at, for scope.
+ * @param context Compilation in progress.
+ * @returns The object literal to pass at runtime, or `null` when the type
+ * cannot be checked honestly.
+ */
+const buildStructuralTest = (type, written, at, context, options = {}) => {
+    const { factory } = context;
+    const generation = {
+        context,
+        at,
+        open: new Set(),
+        recursive: findRecursive(type, context.checker, at),
+        declared: new Map(),
+        counter: { value: 0 },
+    };
+    const parameter = 'v';
+    const body = checkFor(type, factory.createIdentifier(parameter), generation, 0);
+    if (body === null)
+        return null;
+    // Built only where it is asked for. A filter needs yes or no, and emitting a
+    // second walker at every one of those call sites would double the code for
+    // a message nobody reads.
+    const explainer = options.explain === true
+        ? (0, explain_1.buildExplainer)(type, written, at, context.checker, factory, 
+        // Handed the same yes-or-no builder the fast check uses, so the
+        // two can never disagree about what counts as a match. A separate
+        // generation, since the walker and the check number their own
+        // helpers independently.
+        (inner, value) => checkFor(inner, value, {
+            context,
+            at,
+            open: new Set(),
+            recursive: generation.recursive,
+            declared: new Map(),
+            counter: generation.counter,
+        }, 0))
+        : null;
+    const test = factory.createObjectLiteralExpression([
+        factory.createPropertyAssignment('name', factory.createStringLiteral(written)),
+        ...(explainer === null
+            ? []
+            : [factory.createPropertyAssignment('explain', explainer)]),
+        factory.createPropertyAssignment('matches', factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, parameter)], undefined, factory.createToken(typescript_1.default.SyntaxKind.EqualsGreaterThanToken), body)),
+    ], false);
+    if (generation.declared.size === 0)
+        return test;
+    // Recursive types need somewhere to live that is evaluated once rather than
+    // per element, and that does not add a name to the surrounding scope. The
+    // functions are hoisted into a block that runs where the call sits and hands
+    // back the test itself.
+    const statements = [];
+    for (const declaration of generation.declared.values()) {
+        if (declaration.body === undefined)
+            continue;
+        statements.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([
+            factory.createVariableDeclaration(declaration.name, undefined, undefined, declaration.body),
+        ], typescript_1.default.NodeFlags.Const)));
+    }
+    statements.push(factory.createReturnStatement(test));
+    return factory.createCallExpression(factory.createParenthesizedExpression(factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(typescript_1.default.SyntaxKind.EqualsGreaterThanToken), factory.createBlock(statements, true))), undefined, []);
+};
+exports.buildStructuralTest = buildStructuralTest;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fulcro/transform-core",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "Shared machinery behind the Fulcro compile time transformers. Installed for you; not meant to be depended on directly.",
 	"keywords": [
 		"typescript",