uql-codemod 0.48.1 → 0.49.0

package/dist/schemaEntity.js

@@ -0,0 +1,518 @@
+import ts from 'typescript';
+import { formatFindings, locationAt } from './context.js';
+import { CLASS_DEFINERS, definerCall } from './definers.js';
+import { editedText, removeStatement, replaced, replacingUses, reparsedAgain, unedited, } from './edits.js';
+import { unusedImportEdits } from './imports.js';
+import { memberKey, paramFor, quoted } from './keyMaps.js';
+import { KEPT_OPTIONS } from './schemaOptions.js';
+import { arrayElements, decoratorsOf, freeName, hasModifier, identifierText, identifierUses, indentOf, indentUnit, isNamedProperty, objectLiteral, objectProperties, propertyKey, propertyValue, } from './syntax.js';
+/** Imports a converted file may no longer read: the definers folded in, and the brands a schema derives. */
+const FOLDED_IMPORTS = new Set([
+    ...Object.keys(CLASS_DEFINERS).filter((name) => name !== 'defineEntity'),
+    'idKey',
+    'versionKey',
+    'filledKey',
+]);
+const RELATION_KINDS = new Map([
+    ['11', 'oneToOne'],
+    ['m1', 'manyToOne'],
+    ['1m', 'oneToMany'],
+    ['mm', 'manyToMany'],
+]);
+const READ_OPTIONS = new Set([
+    'name',
+    'schema',
+    'extends',
+    'fields',
+    'relations',
+    'hooks',
+    ...KEPT_OPTIONS,
+]);
+/** How each option holding entries is written for its entries to be read one by one: a map of plain properties, or a list. */
+const ENTRY_OPTIONS = {
+    fields: 'map',
+    relations: 'map',
+    hooks: 'map',
+    filters: 'map',
+    indexes: 'list',
+    checks: 'list',
+    triggers: 'list',
+};
+/** Whether `value` is written as `shape` says, so no entry hides in a variable, a spread or a shorthand. */
+function readsAs(value, shape) {
+    return shape === 'list'
+        ? ts.isArrayLiteralExpression(value)
+        : ts.isObjectLiteralExpression(value) && value.properties.every(ts.isPropertyAssignment);
+}
+/** What a class-form relation said that a `rel` builder says by its name and first argument. */
+const RELATION_SHAPE = new Set(['cardinality', 'entity']);
+/**
+ * Declares each class `defineEntity(Class, options)` registered as the schema `defineEntity({ name, ... })`,
+ * folding the string-keyed definers of the same class in. Read off the text the other rewrites produced,
+ * whose options already name members by callback, so it only moves what is written. An entity it cannot
+ * declare faithfully is left as written and reported.
+ */
+export function toSchemaEntities(fileName, text, locate) {
+    if (!CLASS_FORM_CALL.test(text)) {
+        return { ...unedited(text), unresolved: [], notes: [] };
+    }
+    const source = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+    const located = locate ?? ((at) => locationAt(source, at));
+    const unit = indentUnit(source);
+    const unresolved = [];
+    const notes = [];
+    const edits = [];
+    const registrations = collectRegistrations(source, unresolved);
+    const entityCallOf = (calls) => calls.find(({ definer }) => definer === 'defineEntity')?.call;
+    for (const [name, { cls, calls }] of registrations) {
+        const entityCall = entityCallOf(calls);
+        if (!entityCall) {
+            unresolved.push(...calls.map(({ call, definer }) => ({ node: call, message: removedDefiner(definer, name) })));
+            continue;
+        }
+        const base = baseName(entityCall);
+        const baseCall = base && entityCallOf(registrations.get(base)?.calls ?? []);
+        if (baseCall && baseCall.getStart() > entityCall.getStart()) {
+            unresolved.push({
+                node: entityCall,
+                message: `'${name}' extends '${base}', declared below it: move defineEntity(${base}, ...) above this one, then run again`,
+            });
+            continue;
+        }
+        const schema = schemaOf(name, cls, calls, entityCall, unit);
+        if ('message' in schema) {
+            unresolved.push(schema);
+            continue;
+        }
+        notes.push(...schema.notes);
+        edits.push(removeStatement(cls));
+        for (const { call } of calls) {
+            edits.push(call === entityCall ? replaced(call.parent, indented(schema.text, call.parent)) : removeStatement(call.parent));
+        }
+    }
+    return {
+        ...(edits.length
+            ? reparsedAgain(fileName, editedText(text, edits), (edited) => unusedImportEdits(edited, FOLDED_IMPORTS))
+            : unedited(text)),
+        unresolved: formatFindings(unresolved, located),
+        notes: formatFindings(notes, located),
+    };
+}
+/** The class a `defineEntity(Class, { extends })` names as its base, which its schema's const reads where it is declared. */
+function baseName(entityCall) {
+    const options = objectLiteral(entityCall.arguments[1]);
+    return identifierText(options && propertyValue(options, 'extends'));
+}
+/** A call a class-form definer makes, its entity named first: what the pass has anything to do with. */
+const CLASS_FORM_CALL = new RegExp(`\\b(?:${Object.keys(CLASS_DEFINERS).join('|')})\\(\\s*[\\w$.]+\\s*[,)]`);
+/**
+ * Each class the file declares that a class-form definer names, with those calls, in source order. A call naming
+ * anything else, or not written as a statement of its own, is reported: there is no class here to declare.
+ */
+function collectRegistrations(source, unresolved) {
+    const classes = new Map(source.statements
+        .filter((statement) => ts.isClassDeclaration(statement) && !!statement.name)
+        .map((cls) => [cls.name.text, cls]));
+    const registrations = new Map();
+    const visit = (node) => {
+        const read = ts.isCallExpression(node) ? definerCall(node) : undefined;
+        if (read) {
+            const name = identifierText(read.entity);
+            const cls = name ? classes.get(name) : undefined;
+            if (name && cls && ts.isExpressionStatement(node.parent) && node.parent.parent === source) {
+                const registration = registrations.get(name) ?? { cls, calls: [] };
+                registration.calls.push(read);
+                registrations.set(name, registration);
+            }
+            else if (read.definer === 'defineEntity') {
+                unresolved.push({ node, message: 'defineEntity takes a schema now: defineEntity({ name, fields, ... })' });
+            }
+            else {
+                unresolved.push({ node, message: removedDefiner(read.definer, textOf(read.entity)) });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return registrations;
+}
+/** Why an incremental definer naming `entity` has nowhere to fold into. */
+function removedDefiner(definer, entity) {
+    return `${definer} was removed: register '${entity}' with defineEntity in this file, or decorate it (${CLASS_DEFINERS[definer]})`;
+}
+function schemaOf(name, cls, calls, entityCall, unit) {
+    const refused = (message) => ({ node: entityCall, message });
+    const options = objectLiteral(entityCall.arguments[1]) ?? (entityCall.arguments[1] ? undefined : emptyOptions());
+    if (!options || options.properties.some((prop) => !ts.isPropertyAssignment(prop))) {
+        return refused("defineEntity's options could not be read: write them as an object literal");
+    }
+    if (cls.heritageClauses?.length) {
+        return refused(`'${name}' extends a class: declare the base with defineEntity too and pass it as 'extends'`);
+    }
+    if (decoratorsOf(cls).length) {
+        return refused(`'${name}' is decorated as well: declare it one way, decorators or a schema`);
+    }
+    const exported = hasModifier(cls, ts.SyntaxKind.ExportKeyword);
+    if (hasModifier(cls, ts.SyntaxKind.DefaultKeyword)) {
+        return refused(`'${name}' is a default export: export the schema's const by name instead`);
+    }
+    const unread = objectProperties(options).find(({ name: key }) => !READ_OPTIONS.has(propertyKey(key)));
+    if (unread) {
+        return refused(`'${textOf(unread.name)}' has no place in a schema: move it by hand`);
+    }
+    for (const [option, shape] of Object.entries(ENTRY_OPTIONS)) {
+        const value = propertyValue(options, option);
+        if (value && !readsAs(value, shape)) {
+            const literal = shape === 'map' ? 'an object literal of its entries' : 'an array literal';
+            return { node: value, message: `'${option}' could not be read: write it as ${literal}` };
+        }
+    }
+    const scope = {
+        name,
+        param: paramFor(name),
+        rel: freeName('rel', calls.map(({ call }) => call)),
+        relations: new Set([
+            ...objectProperties(propertyValue(options, 'relations')).map((it) => propertyKey(it.name)),
+            ...calls.filter((read) => read.definer === 'defineRelation').map((read) => read.key),
+        ]),
+        methods: new Map(cls.members
+            .filter((member) => ts.isMethodDeclaration(member))
+            .map((method) => [textOf(method.name), method])),
+        hooked: new Map(),
+    };
+    const gathered = {
+        fields: [],
+        computed: [],
+        aggregates: [],
+        relations: new Map(),
+        hooks: new Map(),
+        kept: new Map(),
+    };
+    const { hooked } = scope;
+    const notes = [];
+    for (const read of calls) {
+        const problem = gather(read, read.call === entityCall ? options : undefined, gathered, scope);
+        if (problem) {
+            return problem;
+        }
+    }
+    const member = cls.members.find((it) => !(ts.isPropertyDeclaration(it) && !hasModifier(it, ts.SyntaxKind.StaticKeyword)) &&
+        !(ts.isMethodDeclaration(it) && hooked.has(textOf(it.name))));
+    if (member) {
+        const what = ts.isMethodDeclaration(member) ? 'method' : 'member';
+        const label = member.name ? textOf(member.name) : textOf(member).split('\n')[0];
+        return refused(`'${name}' has the ${what} '${label}': rows are plain objects, so make it a function of the row, then run again`);
+    }
+    for (const [method, declaration] of hooked) {
+        notes.push({
+            node: declaration,
+            message: `'${method}' runs as a hook of the row now, no longer a method of '${name}': call sites need the function`,
+        });
+    }
+    notes.push(...looserTypes(cls, options));
+    const table = propertyValue(options, 'name');
+    const lines = [`name: ${quoted(name)}`, ...(table ? [`table: ${textOf(table)}`] : [])];
+    for (const key of ['schema', 'extends']) {
+        const value = propertyValue(options, key);
+        if (value) {
+            lines.push(`${key}: ${textOf(value)}`);
+        }
+    }
+    const fieldsValue = propertyValue(options, 'fields');
+    const untouched = fieldsValue &&
+        gathered.fields.length === objectProperties(fieldsValue).length &&
+        !gathered.computed.length &&
+        !gathered.aggregates.length;
+    lines.push(`fields: ${untouched ? textOf(fieldsValue) : block(gathered.fields, unit)}`);
+    if (gathered.computed.length) {
+        lines.push(`computed: ${block(gathered.computed, unit)}`);
+    }
+    if (gathered.relations.size) {
+        lines.push(`relations: (${scope.rel}) => (${block([...gathered.relations.values()], unit)})`);
+    }
+    if (gathered.aggregates.length) {
+        lines.push(`aggregates: (${scope.rel}) => (${block(gathered.aggregates, unit)})`);
+    }
+    for (const key of KEPT_OPTIONS) {
+        const entries = gathered.kept.get(key);
+        if (entries) {
+            lines.push(`${key}: ${keptValue(key, entries, propertyValue(options, key))}`);
+        }
+    }
+    if (gathered.hooks.size) {
+        lines.push(`hooks: ${block([...gathered.hooks].map(([event, runs]) => `${event}: [${runs.join(', ')}]`), unit)}`);
+    }
+    const prefix = exported ? 'export ' : '';
+    return {
+        text: `${prefix}const ${name} = defineEntity({\n${lines.map((line) => `${unit}${line},`).join('\n')}\n});\n${prefix}type ${name} = InstanceType<typeof ${name}>;`,
+        notes,
+    };
+}
+const emptyOptions = () => ts.factory.createObjectLiteralExpression();
+/** Entries as an object literal a level in: `{\n    a,\n  }`. */
+function block(entries, unit) {
+    return entries.length ? `{\n${entries.map((entry) => `${unit}${unit}${entry},\n`).join('')}${unit}}` : '{}';
+}
+/** `node`'s text, its lines after the first indented relative to the statement holding it. */
+function textOf(node) {
+    return rebased(node.getText(), node);
+}
+/** `text`, written inside `node`, with the indentation of the statement holding it taken off its lines. */
+function rebased(text, node) {
+    return text.replaceAll(`\n${indentOf(statementOf(node))}`, '\n');
+}
+function statementOf(node) {
+    return ts.isSourceFile(node.parent) ? node : statementOf(node.parent);
+}
+/** `text` replacing `node`, each line after its first indented as `node` is. */
+function indented(text, node) {
+    return text.replaceAll('\n', `\n${indentOf(node)}`);
+}
+/** A kept option's value: as written where nothing was folded into it, its entries joined otherwise. */
+function keptValue(key, entries, written) {
+    if (written && entries.length === entriesOfValue(key, written).length) {
+        return textOf(written);
+    }
+    return ENTRY_OPTIONS[key] === 'map' ? `{ ${entries.join(', ')} }` : `[${entries.join(', ')}]`;
+}
+/** The entries of a kept option as written: a map's properties, a list's elements. */
+function entriesOfValue(key, value) {
+    return ENTRY_OPTIONS[key] === 'map' ? objectProperties(value) : arrayElements(value);
+}
+/**
+ * Adds what one registration declares to `gathered`: `options` for the `defineEntity` call, its arguments for an
+ * incremental definer. Returns why it cannot, where it cannot.
+ */
+function gather({ call, definer, key, options: third, rest }, options, gathered, { name, param, rel, relations, methods, hooked }) {
+    const unreadable = {
+        node: call,
+        message: `${definer}'s arguments could not be read: fold them into defineEntity by hand`,
+    };
+    const addHook = (event, method) => {
+        const declaration = methods.get(method);
+        if (!declaration) {
+            return { node: call, message: `the hook '${method}' names no method of the class` };
+        }
+        const run = hookFunction(declaration, param);
+        if (!run) {
+            return {
+                node: declaration,
+                message: `'${method}' takes more than the hook context: make it a function of the row by hand`,
+            };
+        }
+        hooked.set(method, declaration);
+        const runs = gathered.hooks.get(event) ?? [];
+        runs.push(run);
+        gathered.hooks.set(event, runs);
+        return undefined;
+    };
+    const addField = (key, entry, fieldOptions, node) => {
+        const aggregate = key && aggregateEntry(`${name}.${key}`, key, fieldOptions, relations, rel);
+        if (typeof aggregate === 'string') {
+            gathered.aggregates.push(aggregate);
+            return undefined;
+        }
+        if (aggregate) {
+            return { node, message: aggregate.message };
+        }
+        (isComputed(fieldOptions) ? gathered.computed : gathered.fields).push(entry);
+        return undefined;
+    };
+    const addRelation = (key, value) => {
+        const built = key && relationEntry(key, value, rel);
+        if (built) {
+            gathered.relations.set(key, built);
+        }
+        return !!built;
+    };
+    const addKept = (option, entries) => {
+        const kept = gathered.kept.get(option) ?? [];
+        kept.push(...entries);
+        gathered.kept.set(option, kept);
+    };
+    if (options) {
+        for (const field of objectProperties(propertyValue(options, 'fields'))) {
+            const problem = addField(propertyKey(field.name), textOf(field), field.initializer, field);
+            if (problem)
+                return problem;
+        }
+        for (const relation of objectProperties(propertyValue(options, 'relations'))) {
+            if (!addRelation(propertyKey(relation.name), relation.initializer)) {
+                return {
+                    node: relation,
+                    message: 'a relation could not be read: write it as rel.<kind>(Target, { ... }) by hand',
+                };
+            }
+        }
+        for (const hook of objectProperties(propertyValue(options, 'hooks'))) {
+            const listed = hookMethods(hook.initializer);
+            if (!listed) {
+                return { node: hook, message: 'a hook list could not be read: write its functions by hand' };
+            }
+            for (const method of listed) {
+                const problem = addHook(textOf(hook.name), method);
+                if (problem)
+                    return problem;
+            }
+        }
+        for (const option of KEPT_OPTIONS) {
+            const value = propertyValue(options, option);
+            if (value) {
+                addKept(option, entriesOfValue(option, value).map((it) => textOf(it)));
+            }
+        }
+        return undefined;
+    }
+    switch (definer) {
+        case 'defineEntity':
+            return unreadable;
+        case 'defineField':
+        case 'defineId': {
+            if (!key || !third)
+                return unreadable;
+            const value = definer === 'defineId' ? withIsId(third) : textOf(third);
+            if (!value)
+                return unreadable;
+            return addField(key, `${memberKey(key)}: ${value}`, third, call);
+        }
+        case 'defineRelation':
+            return third && addRelation(key, third) ? undefined : unreadable;
+        case 'defineHook': {
+            const event = third && ts.isStringLiteralLike(third) ? third.text : undefined;
+            return key && event ? addHook(event, key) : unreadable;
+        }
+        case 'defineIndex':
+            if (!third)
+                return unreadable;
+            addKept('indexes', [textOf(third)]);
+            return undefined;
+        case 'defineTrigger':
+            if (!rest.length)
+                return unreadable;
+            addKept('triggers', rest.map((it) => textOf(it)));
+            return undefined;
+        case 'defineFilter':
+            if (!key || !third)
+                return unreadable;
+            addKept('filters', [`${memberKey(key)}: ${textOf(third)}`]);
+            return undefined;
+    }
+}
+/** Whether a field's options compute it, which a schema declares under `computed`. */
+function isComputed(options) {
+    const literal = objectLiteral(options);
+    return !!literal && propertyValue(literal, 'computed') !== undefined;
+}
+/** `{ ...options, isId: true }` written into a literal's own text, or nothing where it is not one. */
+function withIsId(options) {
+    const literal = objectLiteral(options);
+    if (!literal)
+        return undefined;
+    const text = textOf(literal);
+    return literal.properties.length ? text.replace(/^\{\s*/, '{ isId: true, ') : '{ isId: true }';
+}
+/** `author: () => rel.manyToOne(User, { references })` from `{ cardinality: 'm1', entity: () => User, references }`. */
+function relationEntry(key, value, rel) {
+    const relation = objectLiteral(value);
+    const cardinality = relation && propertyValue(relation, 'cardinality');
+    const getter = relation && propertyValue(relation, 'entity');
+    const kind = cardinality && ts.isStringLiteralLike(cardinality) ? RELATION_KINDS.get(cardinality.text) : undefined;
+    if (!relation || !kind || !getter || !ts.isArrowFunction(getter) || ts.isBlock(getter.body)) {
+        return undefined;
+    }
+    const properties = relation.properties.filter(isNamedProperty);
+    if (properties.length !== relation.properties.length) {
+        return undefined;
+    }
+    const rest = properties.filter((prop) => !RELATION_SHAPE.has(propertyKey(prop.name))).map((prop) => textOf(prop));
+    const args = [textOf(getter.body), ...(rest.length ? [`{ ${rest.join(', ')} }`] : [])];
+    return `${memberKey(key)}: () => ${rel}.${kind}(${args.join(', ')})`;
+}
+/** The methods a hook list names, `(post) => [post.stamp]`, or nothing where it is not one. */
+function hookMethods(list) {
+    if (!ts.isArrowFunction(list) || !ts.isArrayLiteralExpression(list.body) || list.parameters.length !== 1) {
+        return undefined;
+    }
+    const param = identifierText(list.parameters[0].name);
+    const names = list.body.elements.map((entry) => ts.isPropertyAccessExpression(entry) && identifierText(entry.expression) === param ? entry.name.text : undefined);
+    return names.every((it) => it !== undefined) ? names : undefined;
+}
+/** A hook method as a function of the row: `this` read as the row, named `preferred` where the body leaves it free. */
+function hookFunction(method, preferred) {
+    if (!method.body || method.parameters.length > 1) {
+        return undefined;
+    }
+    const row = freeName(preferred, [method]);
+    const isAsync = hasModifier(method, ts.SyntaxKind.AsyncKeyword);
+    const params = [row, ...method.parameters.map((it) => textOf(it))].join(', ');
+    const body = method.body;
+    const uses = [];
+    const visit = (node) => {
+        if (node.kind === ts.SyntaxKind.ThisKeyword) {
+            uses.push(node);
+        }
+        else if (!ts.isFunctionLike(node) || ts.isArrowFunction(node)) {
+            ts.forEachChild(node, visit);
+        }
+    };
+    ts.forEachChild(body, visit);
+    return `${isAsync ? 'async ' : ''}(${params}) => ${substituted(body, uses, row)}`;
+}
+/**
+ * `total: () => rel.items.count()` from a field computed over a relation, `{ computed: (counted) => counted.items.count() }`,
+ * which a schema declares among its aggregates; nothing for a field reading no relation, and why where it cannot move.
+ */
+function aggregateEntry(label, key, options, relations, rel) {
+    const literal = objectLiteral(options);
+    const computed = literal && propertyValue(literal, 'computed');
+    const param = computed && ts.isArrowFunction(computed) ? identifierText(computed.parameters[0]?.name) : undefined;
+    if (!computed || !ts.isArrowFunction(computed) || !param) {
+        return undefined;
+    }
+    const uses = identifierUses(computed.body, param);
+    const overRelation = (use) => ts.isPropertyAccessExpression(use.parent) && use.parent.expression === use && relations.has(use.parent.name.text);
+    if (!uses.some(overRelation)) {
+        return undefined;
+    }
+    if (literal.properties.length > 1) {
+        return { message: `'${label}' aggregates a relation with options an aggregate takes none of: move it by hand` };
+    }
+    if (ts.isBlock(computed.body) || !uses.every(overRelation)) {
+        return { message: `'${label}' reads more than a relation's aggregate: move it by hand` };
+    }
+    return `${memberKey(key)}: () => ${substituted(computed.body, uses, rel)}`;
+}
+/** `body`'s text, rebased, with each of `uses` written as `replacement`. */
+function substituted(body, uses, replacement) {
+    return rebased(replacingUses(body, uses, replacement), body);
+}
+/** Notes each property the class typed more narrowly than its schema derives, with the option that keeps it. */
+function looserTypes(cls, options) {
+    const fields = objectLiteral(propertyValue(options, 'fields'));
+    return cls.members.flatMap((member) => {
+        const key = ts.isPropertyDeclaration(member) ? propertyKey(member.name) : undefined;
+        const declared = ts.isPropertyDeclaration(member) ? member.type : undefined;
+        const field = key && fields ? objectLiteral(propertyValue(fields, key)) : undefined;
+        if (!key || !declared || !field) {
+            return [];
+        }
+        const written = textOf(declared);
+        const said = (option) => propertyValue(field, option) !== undefined;
+        if (/\bJson</.test(written) && !said('shape')) {
+            return [
+                {
+                    node: member,
+                    message: `'${key}' was declared ${written}: describe its payload with 'shape' to keep it typed`,
+                },
+            ];
+        }
+        const literals = ts.isUnionTypeNode(declared) &&
+            declared.types.filter((type) => ts.isLiteralTypeNode(type) && ts.isStringLiteral(type.literal));
+        if (literals && literals.length > 1 && !said('enum')) {
+            return [
+                { node: member, message: `'${key}' was declared ${written}: list its values in 'enum' to keep them typed` },
+            ];
+        }
+        return [];
+    });
+}

package/dist/schemaOptions.d.ts

@@ -0,0 +1,6 @@
+/** The options a schema's first call keeps, each as it is written there. */
+export declare const FIRST_CALL_OPTIONS: readonly ["name", "table", "schema", "abstract", "extends", "fields"];
+/** The sections a schema chains after its first call, in the order it chains them, `relations` last. */
+export declare const CHAINED_OPTIONS: readonly ["computed", "indexes", "checks", "triggers", "filters", "hooks"];
+/** The options a class-form `defineEntity` took that a schema keeps as they are, and that incremental definers add to. */
+export declare const KEPT_OPTIONS: readonly ["indexes", "checks", "filters", "triggers"];

package/dist/schemaOptions.js

@@ -0,0 +1,6 @@
+/** The options a schema's first call keeps, each as it is written there. */
+export const FIRST_CALL_OPTIONS = ['name', 'table', 'schema', 'abstract', 'extends', 'fields'];
+/** The sections a schema chains after its first call, in the order it chains them, `relations` last. */
+export const CHAINED_OPTIONS = ['computed', 'indexes', 'checks', 'triggers', 'filters', 'hooks'];
+/** The options a class-form `defineEntity` took that a schema keeps as they are, and that incremental definers add to. */
+export const KEPT_OPTIONS = ['indexes', 'checks', 'filters', 'triggers'];

package/dist/statementSql.d.ts

@@ -1,7 +1,8 @@
 import ts from 'typescript';
+import { type Part } from './edits.js';
 /**
  * A querier's `run(sql, values)` statement as the template its tag takes, each placeholder replaced by the value
  * it binds, or nothing where that is not certain: the SQL is no literal, or the values no array literal of
  * plain elements, or its placeholders cannot be told apart from the rest of the text.
  */
-export declare function statementTemplate(sql: ts.Expression, values: readonly ts.Expression[]): string | undefined;
+export declare function statementTemplate(sql: ts.Expression, values: readonly ts.Expression[]): readonly Part[] | undefined;

package/dist/statementSql.js

@@ -1,5 +1,6 @@
 import ts from 'typescript';
-import { templateOf } from './entitySql.js';
+import { original } from './edits.js';
+import { templateOf, templateWith } from './entitySql.js';
 /**
  * A quoted string or identifier, or a comment, skipped; a `?` or `$n` placeholder; or a character a placeholder
  * could hide behind that this does not read: an unclosed quote or comment, a backslash, a `#`, any other `$`.
@@ -40,7 +41,7 @@ export function statementTemplate(sql, values) {
         return undefined;
     }
     if (!values.length) {
-        return templateOf([sql.text]);
+        return [templateOf(sql.text)];
     }
     const [list] = values;
     const elements = ts.isArrayLiteralExpression(list) ? list.elements : undefined;
@@ -48,6 +49,11 @@ export function statementTemplate(sql, values) {
         return undefined;
     }
     const placeholders = placeholdersOf(sql.text, elements.length);
-    return (placeholders &&
-        templateOf(placeholders.texts, placeholders.values.map((at) => elements[at].getText())));
+    if (!placeholders || placeholders.values.some((at) => isReused(placeholders.values, at) && !isPlain(elements[at]))) {
+        return undefined;
+    }
+    return templateWith(placeholders.texts, placeholders.values.map((at) => original(elements[at])));
 }
+/** A value read twice in the template is evaluated twice, which only a name or a literal can do unseen. */
+const isPlain = (value) => ts.isIdentifier(value) || ts.isNumericLiteral(value) || ts.isStringLiteral(value);
+const isReused = (values, at) => values.filter((value) => value === at).length > 1;

package/dist/syntax.d.ts

@@ -5,18 +5,72 @@ export declare function identifierText(node: ts.Node | undefined): string | unde
 export declare function propertyKey(name: ts.PropertyName): string | undefined;
 /** A property of an object literal written with its own name: a plain or quoted key, or a shorthand. */
 export type NamedProperty = ts.PropertyAssignment | ts.ShorthandPropertyAssignment;
+export declare function isNamedProperty(prop: ts.ObjectLiteralElementLike): prop is NamedProperty;
 /** The property `name` of an object literal, a shorthand included. */
 export declare function namedProperty(node: ts.ObjectLiteralExpression, name: string): NamedProperty | undefined;
+/** The key a property is written under, a shorthand's included; nothing for a spread, a method or a computed key. */
+export declare function keyOf(prop: ts.ObjectLiteralElementLike): string | undefined;
+/**
+ * What the codemod can see of an options object. `opaque` is one it cannot write into without dropping what
+ * the author put there: `@Field(shared)`, or `{ ...base }`, whose spread may carry the option and would win.
+ */
+export type Options = {
+    readonly kind: 'empty';
+    readonly call: ts.CallExpression;
+} | {
+    readonly kind: 'literal';
+    readonly node: ts.ObjectLiteralExpression;
+} | {
+    readonly kind: 'opaque';
+    readonly reason: string;
+};
+/** The options `value` writes: a literal to read and write into, or why it is not one. */
+export declare function optionsOf(value: ts.Expression): Exclude<Options, {
+    kind: 'empty';
+}>;
+/**
+ * An object literal's named properties by key, each as its value (a shorthand's value is its name), or `undefined`
+ * where `node` is no literal or one of its properties is spread, computed or a method.
+ */
+export declare function propertiesByKey(node: ts.Expression): Map<string, ts.Expression> | undefined;
+/** A method called on a chain: the call, the method's name, and the receiver it is called on. */
+export type ChainMethod = {
+    readonly call: ts.CallExpression;
+    readonly name: string;
+    readonly receiver: ts.Expression;
+};
+/** The root a method chain starts from, and its methods in source order: `f.string().nullable()` is `f` and two. */
+export declare function chainOf(node: ts.Expression): {
+    readonly root: ts.Expression;
+    readonly methods: readonly ChainMethod[];
+};
+export declare function hasModifier(node: ts.Node, kind: ts.ModifierSyntaxKind): boolean;
+/** `preferred`, or it numbered past every name `nodes` mention, so a parameter named so shadows nothing they read. */
+export declare function freeName(preferred: string, nodes: readonly ts.Node[]): string;
+/** Each identifier in `node` naming `name`, in source order, nested functions included, but none a member named so. */
+export declare function identifierUses(node: ts.Node, name: string): ts.Identifier[];
+/** Whether `node` reads a binding named `name`, which a callback parameter of that name would shadow: stops at the first. */
+export declare function mentions(node: ts.Node, name: string): boolean;
 /** The property `name` of an object literal that is written with a value. */
 export declare function propertyAssignment(node: ts.ObjectLiteralExpression, name: string): ts.PropertyAssignment | undefined;
 export declare function propertyValue(node: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined;
 /** The property assignments of an object literal, or none where `node` is not one. */
 export declare function objectProperties(node: ts.Expression | undefined): readonly ts.PropertyAssignment[];
+/** The entries of a column list, written as an array or returned by its callback. */
+export declare function columnListEntries(list: ts.Expression | undefined): readonly ts.Expression[];
 /** The elements of an array literal, or none where `node` is not one. */
 export declare function arrayElements(node: ts.Expression | undefined): readonly ts.Expression[];
 /** `node` where it is an object literal. */
 export declare function objectLiteral(node: ts.Expression | undefined): ts.ObjectLiteralExpression | undefined;
+/** One level of indentation as the file writes it: the shallowest indent of its code, two spaces where it has none. */
+export declare function indentUnit(source: ts.SourceFile): string;
 /** A node's decorators, or none where it is a kind that cannot carry them. */
 export declare function decoratorsOf(node: ts.Node): readonly ts.Decorator[];
 /** `Field` for `@Field` and `@Field(...)`. */
 export declare function decoratorName(node: ts.Decorator): string | undefined;
+/** The decorators declaring a field: `@Field`, and `@Id` for the key the class names. */
+export declare const FIELD_DECORATORS: ReadonlySet<string | undefined>;
+/** Where the line holding offset `at` of `text` starts. */
+export declare function lineStartOf(text: string, at: number): number;
+/** The whitespace the line holding `node` starts with. */
+export declare function indentOf(node: ts.Node): string;