uql-codemod 0.47.0 → 0.47.1

package/dist/imports.js

@@ -0,0 +1,314 @@
+import ts from 'typescript';
+import { inserted, removeFromList, removeStatement, replaced } from './edits.js';
+/**
+ * Exports that no longer exist, mapped to what to do instead. Reported rather than rewritten: what replaces
+ * each is decided at its call site.
+ */
+const REMOVED_EXPORTS = new Map([
+    [
+        'setQuerierPool',
+        'pass the pool where it is used: `createFetchHandler({ pool, include })`, `querierMiddleware({ pool, include })`',
+    ],
+    ['getQuerierPool', 'take the pool from the module that builds it, or from Nest DI'],
+    ['getQuerier', 'use `pool.withQuerier(...)` / `pool.transaction(...)`, which release the connection'],
+    ['ClientQuerierPool', "construct the `HttpQuerier` where it is used, `new HttpQuerier('/api')`"],
+    ['QueryWhereFieldMap', 'use `QueryWhere`'],
+    ['QueryStreamProjected', 'use `QueryProjected`'],
+    ['RelationMappedBy', "a 'mappedBy' is `(keys: KeyMap<E>) => Key<E>` now"],
+    ['RelationKeyMapper', 'it is `(keys: KeyMap<E>) => Key<E>` now'],
+    ['augmentWhere', 'spread the two maps: `{ ...where, ...extra }`'],
+    ['buildQueryWhereAsMap', 'a `$where` is a map already; name the key for ids: `{ id: [1, 2] }`'],
+    ['AbstractPgQuerier', 'every pg-compatible pool returns `PgQuerier` (`uql-orm/postgres`), which is concrete'],
+    ['AbstractHranaQuerierPool', 'extend `AbstractSqlQuerierPool` and hand every querier a `HranaQuerier`'],
+    [
+        'PreparedSqliteQuerier',
+        'use `SqliteQuerier`, which takes any driver that prepares, or extend `AbstractSqliteQuerier`',
+    ],
+    ['toSqliteBindValues', 'pass the values as they are: every SQLite driver binds a `SqliteBindValue[]`'],
+    ['libsqlUseRemoteForMigrations', '`LibsqlQuerierPool.getMigrationQuerier()` decides it'],
+    ['SqlCallback', 'use `EntitySql<E>`, which holds the callback form'],
+    [
+        'IndexColumnOptions',
+        "an entity's index entry is `EntityIndexColumnInput<E>`, the migration builder's `IndexColumnInput`",
+    ],
+    ['isKnownMigratorDialect', 'every dialect has a migrator, so it always held: drop the check'],
+    ['QuerierPoolDialect', "read the pool's own: `P['dialect']`"],
+    ['QuerierPoolQuerier', "read the pool's own: `Awaited<ReturnType<P['getQuerier']>>`"],
+    [
+        'POSTGRES_WIRE_DRIVER_CAPABILITIES',
+        'pass `driverCapabilities: { nativeArrays: false, explicitJsonCast: true }` to the dialect',
+    ],
+    ['MysqlLikeSqlDialect', 'extend `MySqlDialect` (`uql-orm/mysql`) or `MariaDialect` (`uql-orm/mariadb`)'],
+    ['D1Meta', "uql reads `D1Result['meta']`; the rest of a binding is typed by `@cloudflare/workers-types`"],
+    ['D1ExecResult', 'the rest of a binding is typed by `@cloudflare/workers-types`'],
+    ['createSchemaGenerator', 'use `new SqlSchemaGenerator(dialect)`, or `migrator.getSchemaGenerator()`'],
+    ...['JsonMigrationStorage', 'DatabaseMigrationStorage', 'MongoMigrationStorage'].map((name) => [name, 'the migrator keeps its journal in the database itself, named by `tableName`']),
+]);
+/** What `uql-orm/util` exported that the root still does. */
+const UTIL_ROOT_EXPORTS = [
+    'currentDate',
+    'currentTime',
+    'currentTimestamp',
+    'raw',
+    'refs',
+    'uuid',
+    'uuidv7',
+    'deleteFrom',
+    'insertInto',
+    'refuse',
+    'updateTable',
+    'upsertInto',
+    'withDeleted',
+    'HookContext',
+    'DefaultLogger',
+];
+/**
+ * Exports renamed or moved and nothing else, so the import and every use follow, the import moving to `from`
+ * where the name lives in another entry. Keyed by name, or by `entry#name` where the name stays elsewhere.
+ */
+const RENAMED_EXPORTS = new Map([
+    ['QueryWhereMap', { to: 'QueryWhere' }],
+    ['RelationKeyMap', { to: 'KeyMap' }],
+    ['FilterCondition', { to: 'FilterWhere' }],
+    ['PgDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['NeonDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['PgliteDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['CrdbQuerier', { to: 'PgQuerier', from: 'uql-orm/postgres' }],
+    ['NeonQuerier', { to: 'PgQuerier', from: 'uql-orm/postgres' }],
+    ['MySql2Dialect', { to: 'MySqlDialect', from: 'uql-orm/mysql' }],
+    ['MongodbNativeDialect', { to: 'MongoDialect', from: 'uql-orm/mongodb' }],
+    ['LibsqlQuerier', { to: 'HranaQuerier', from: 'uql-orm/sqlite' }],
+    ['TursoQuerier', { to: 'HranaQuerier', from: 'uql-orm/sqlite' }],
+    ['TursoLocalQuerier', { to: 'SqliteQuerier', from: 'uql-orm/sqlite' }],
+    ['TursoDatabase', { to: 'SqliteDatabase', from: 'uql-orm/sqlite' }],
+    ['SqlMigrationModuleOptions', { to: 'MigrationModuleOptions' }],
+    ['buildSqlQuerierMigrationModule', { to: 'buildMigrationModule' }],
+    ['QueryDialect', { to: 'SqlQueryDialect' }],
+    ['EngineFeatures', { to: 'DialectFeatures' }],
+    ['KnownMigratorDialect', { to: 'DialectName', from: 'uql-orm' }],
+    ['D1Preparer', { to: 'D1Queryable' }],
+    ['D1Database', { to: 'D1Queryable', from: 'uql-orm/d1' }],
+    ['MongoQuerier', { to: 'MongoQuerier', from: 'uql-orm/mongodb' }],
+    ['isMongoQuerier', { to: 'isMongoQuerier', from: 'uql-orm/mongodb' }],
+    ['MongoSchemaIntrospector', { to: 'MongoSchemaIntrospector', from: 'uql-orm/mongodb' }],
+    ['Sqlite3QuerierPool', { to: 'SqliteQuerierPool' }],
+    ['Sqlite3PoolOptions', { to: 'SqlitePoolOptions' }],
+    ['IMigrationBuilder', { to: 'MigrationBuilder' }],
+    ['ITableBuilder', { to: 'TableBuilder' }],
+    ['IAlterTableBuilder', { to: 'AlterTableBuilder' }],
+    ['IColumnBuilder', { to: 'ColumnBuilder' }],
+    ['IColumnFactory', { to: 'ColumnFactory' }],
+    ['IForeignKeyBuilder', { to: 'ForeignKeyBuilder' }],
+    ['ITableForeignKeyBuilder', { to: 'TableForeignKeyBuilder' }],
+    ['UqlLockUsageError', { to: 'UqlUsageError' }],
+    ['uql-orm/http#Hook', { to: 'RequestHook' }],
+    ['uql-orm/http#HookContext', { to: 'RequestHookContext' }],
+    ...UTIL_ROOT_EXPORTS.map((name) => [`uql-orm/util#${name}`, { to: name, from: 'uql-orm' }]),
+]);
+/** What the root exported that is internal now, and what to write instead. */
+const INTERNAL_EXPORTS = new Map([
+    ...['AbstractDialect', 'AbstractSqlDialect', 'AbstractQuerier', 'AbstractQuerierPool'].map((name) => [name, "extend a driver's dialect or pool from its entry instead"]),
+    ...['AbstractSqlQuerier', 'AbstractSqlQuerierPool'].map((name) => [name, "extend a driver's querier or pool from its entry instead"]),
+    ['SqlQueryContext', 'make one with `dialect.createContext()`, typed `QueryContext`'],
+    ['dialectOptionsFrom', "pass the options to the driver's dialect"],
+    ...['fieldOf', 'relationOf', 'soleIdOf', 'assertSoleId'].map((name) => [name, 'read the field off `getMeta(Entity).fields`']),
+    ['namesKey', 'read the keys off `getMeta(Entity).ids`'],
+    ['getEntities', 'list your entities in the config'],
+]);
+/** Entries renamed, or dropped for repeating the root, each to the one now exporting what it did. */
+const MOVED_ENTRIES = new Map([
+    ['uql-orm/maria', 'uql-orm/mariadb'],
+    ['uql-orm/mongo', 'uql-orm/mongodb'],
+    ['uql-orm/bunSql', 'uql-orm/bun-sql'],
+    ['uql-orm/dialect', 'uql-orm'],
+    ['uql-orm/entity', 'uql-orm'],
+    ['uql-orm/namingStrategy', 'uql-orm'],
+    ['uql-orm/querier', 'uql-orm'],
+    ['uql-orm/type', 'uql-orm'],
+]);
+/**
+ * The file's named imports from `uql-orm`. `entries` adds the driver entries (`uql-orm/postgres`, ...),
+ * for what is read by name only: `idKey` written into one would land on an entry that may not export it.
+ */
+export function uqlImportDeclarations(source, entries = false) {
+    return source.statements.flatMap((declaration) => {
+        if (!ts.isImportDeclaration(declaration) || !ts.isStringLiteral(declaration.moduleSpecifier)) {
+            return [];
+        }
+        const entry = declaration.moduleSpecifier.text;
+        if (entry !== 'uql-orm' && !(entries && entry.startsWith('uql-orm/'))) {
+            return [];
+        }
+        const bindings = declaration.importClause?.namedBindings;
+        return bindings && ts.isNamedImports(bindings) ? [{ declaration, entry, elements: bindings.elements }] : [];
+    });
+}
+function uqlImports(source, entries = false) {
+    return uqlImportDeclarations(source, entries).flatMap(({ elements }) => elements);
+}
+/** The specifier importing the export `name` from `uql-orm`, or with `entries` from any of its entries. */
+export function uqlImport(source, name, entries = false) {
+    return uqlImports(source, entries).find((element) => importedName(element) === name);
+}
+/** The name an import specifier brings in, which is the original one where it was renamed. */
+function importedName(element) {
+    return (element.propertyName ?? element.name).text;
+}
+/** Every identifier in the file bound to the same symbol as `name`, besides `name` itself. */
+export function usesOf(source, name, checker) {
+    const symbol = checker.getSymbolAtLocation(name);
+    const uses = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && node !== name && node.text === name.text) {
+            if (symbol && checker.getSymbolAtLocation(node) === symbol) {
+                uses.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return uses;
+}
+/** The rename `element` still needs, none where it already names the export at its entry. */
+function renamedTo(element, entry) {
+    const name = importedName(element);
+    const rename = RENAMED_EXPORTS.get(`${entry}#${name}`) ?? RENAMED_EXPORTS.get(name);
+    return rename?.to === name && rename.from === entry ? undefined : rename;
+}
+/** Names an export that no longer exists, where it is imported from the package or one of its entries. */
+export function reportRemovedExports(ctx) {
+    for (const { declaration, entry, elements } of uqlImportDeclarations(ctx.source, true)) {
+        if (entry === 'uql-orm/util') {
+            const names = elements.filter((element) => !renamedTo(element, entry)).map(importedName);
+            if (names.length) {
+                ctx.report(declaration, `'uql-orm/util' was removed; its helpers are internal, so write your own \`${names.join('`, `')}\``);
+            }
+            continue;
+        }
+        const root = (MOVED_ENTRIES.get(entry) ?? entry) === 'uql-orm';
+        for (const element of elements) {
+            const name = importedName(element);
+            const removed = REMOVED_EXPORTS.get(name);
+            const internal = root ? INTERNAL_EXPORTS.get(name) : undefined;
+            if (removed) {
+                ctx.report(element, `'${name}' was removed; ${removed}`);
+            }
+            else if (internal) {
+                ctx.report(element, `'${name}' is internal; ${internal}`);
+            }
+        }
+    }
+}
+/**
+ * Rewrites each import naming a {@link RENAMED_EXPORTS} export, or from a {@link MOVED_ENTRIES} entry, renaming
+ * every use: a name moving entries gets an import from its new one, and one the file already imports is dropped,
+ * as is a `dead` one. Returns the rewritten imports, which nothing else may edit.
+ */
+export function renameExports(dead, ctx) {
+    const imports = uqlImportDeclarations(ctx.source, true);
+    const kept = imports.flatMap(({ entry, elements }) => elements.filter((element) => !renamedTo(element, entry)));
+    const bound = new Set(kept.map((element) => element.name.text));
+    const rewritten = new Set();
+    for (const { declaration, entry: imported, elements } of imports) {
+        const entry = MOVED_ENTRIES.get(imported) ?? imported;
+        if (entry === imported && !elements.some((element) => renamedTo(element, entry))) {
+            continue;
+        }
+        const byEntry = new Map([[entry, []]]);
+        for (const element of elements.filter(({ name }) => !dead.has(name.text))) {
+            const rename = renamedTo(element, entry);
+            const local = element.propertyName || !rename ? element.name.text : rename.to;
+            if (rename && !element.propertyName) {
+                ctx.edits.push(...usesOf(ctx.source, element.name, ctx.checker).map((use) => replaced(use, rename.to)));
+            }
+            if (rename && bound.has(local)) {
+                continue;
+            }
+            bound.add(local);
+            const target = rename?.from ?? entry;
+            const text = rename
+                ? `${element.isTypeOnly ? 'type ' : ''}${rename.to}${element.propertyName ? ` as ${local}` : ''}`
+                : element.getText();
+            byEntry.set(target, [...(byEntry.get(target) ?? []), text]);
+        }
+        const keyword = isTypeOnly(declaration) ? 'import type' : 'import';
+        const quote = declaration.moduleSpecifier.getText()[0];
+        const statements = [...byEntry]
+            .filter(([, names]) => names.length)
+            .map(([from, names]) => `${keyword} { ${names.join(', ')} } from ${quote}${from}${quote};`);
+        ctx.edits.push(statements.length ? replaced(declaration, statements.join('\n')) : removeStatement(declaration));
+        rewritten.add(declaration);
+    }
+    return rewritten;
+}
+function isTypeOnly(declaration) {
+    return declaration.importClause?.phaseModifier === ts.SyntaxKind.TypeKeyword;
+}
+/**
+ * The imported names the codemod removes once every use was rewritten: `Relation` unwrapped and `expr` defaults.
+ * A removed decorator keeps its import on purpose: deleting it would swap a clear error for a puzzling one.
+ */
+export function deadImportNames(ctx) {
+    const { source, rewritten } = ctx;
+    const uses = (name) => {
+        const element = uqlImport(source, name, true);
+        return element ? usesOf(source, element.name, ctx.checker).length : 0;
+    };
+    const relations = uses('Relation');
+    if (relations > rewritten.Relation) {
+        ctx.unresolved.push(`${source.fileName}: ${relations - rewritten.Relation} 'Relation<T>' reference(s) are somewhere this codemod ` +
+            'does not rewrite; unwrap them and drop the import by hand');
+    }
+    const names = ['Relation', 'expr'];
+    return new Set(names.filter((name) => rewritten[name] > 0 && rewritten[name] === uses(name)));
+}
+/**
+ * Removes `import 'reflect-metadata'`, since the polyfill only ever fed `design:type`, and each `dead` name
+ * from the imports {@link renameExports} left as written, having left the dead names out of the rest.
+ */
+export function dropDeadImports(dead, rewritten, ctx) {
+    for (const statement of ctx.source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+            continue;
+        }
+        if (statement.moduleSpecifier.text === 'reflect-metadata' && !statement.importClause) {
+            ctx.edits.push(removeStatement(statement));
+            continue;
+        }
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named) || rewritten.has(statement)) {
+            continue;
+        }
+        const dropped = named.elements.filter((element) => dead.has(element.name.text));
+        if (dropped.length === named.elements.length && !statement.importClause?.name) {
+            ctx.edits.push(removeStatement(statement));
+            continue;
+        }
+        for (const element of dropped) {
+            ctx.edits.push(removeFromList(named.elements, element, ctx.source));
+        }
+    }
+}
+/**
+ * Imports what the rewrites wrote (`idKey`, `raw`) into the file's own `uql-orm` import. Reported instead
+ * where there is none: the package may be imported under a path this codemod does not recognise.
+ */
+export function addImports(rewritten, ctx) {
+    const { source } = ctx;
+    const imported = new Set(uqlImports(source).map(importedName));
+    const missing = [...ctx.imports].filter(([name]) => !imported.has(name));
+    if (!missing.length) {
+        return;
+    }
+    const anchor = uqlImportDeclarations(source).find(({ declaration }) => !rewritten.has(declaration));
+    if (!anchor) {
+        for (const [name, what] of missing) {
+            ctx.unresolved.push(`${source.fileName}: import '${name}' from 'uql-orm' for ${what} written here`);
+        }
+        return;
+    }
+    const names = missing.map(([name]) => name);
+    ctx.edits.push(isTypeOnly(anchor.declaration)
+        ? inserted(anchor.declaration, `import { ${names.join(', ')} } from 'uql-orm';\n`)
+        : inserted(anchor.elements[0], names.map((name) => `${name}, `).join('')));
+}

package/dist/keyMaps.d.ts

@@ -8,10 +8,6 @@ export declare function paramFor(className: string | undefined): string;
 export declare function quoted(text: string): string;
 /** `post.title`, or `post['first-name']` for a key that is no identifier. */
 export declare function memberAccess(param: string, key: string): string;
-/** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
-export declare function propertyKey(name: ts.PropertyName): string | undefined;
-/** The initializer of the property `name` in an object literal, however its key is written. */
-export declare function propertyValue(node: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined;
 /** `'amount'` or `['title', 'body']` -> `{ amount: true }`, the key map a statement names fields by. */
 export declare function fieldKeysEdits(value: ts.Expression): Edits;
 /** Whether `value` is already a function, the form every rewrite here produces. */

package/dist/keyMaps.js

@@ -1,5 +1,6 @@
 import ts from 'typescript';
 import { inserted, replaced } from './edits.js';
+import { identifierText, propertyValue } from './syntax.js';
 /** A callback's parameter, named after the class it reads: `Post` -> `post`. */
 export function paramFor(className) {
     return className ? className[0].toLowerCase() + className.slice(1) : 'entity';
@@ -15,15 +16,6 @@ export function quoted(text) {
 export function memberAccess(param, key) {
     return isIdentifierName(key) ? `${param}.${key}` : `${param}[${quoted(key)}]`;
 }
-/** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
-export function propertyKey(name) {
-    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
-}
-/** The initializer of the property `name` in an object literal, however its key is written. */
-export function propertyValue(node, name) {
-    const property = node.properties.find((prop) => ts.isPropertyAssignment(prop) && propertyKey(prop.name) === name);
-    return property?.initializer;
-}
 /** `'amount'` or `['title', 'body']` -> `{ amount: true }`, the key map a statement names fields by. */
 export function fieldKeysEdits(value) {
     const names = ts.isArrayLiteralExpression(value) ? value.elements : [value];
@@ -63,7 +55,7 @@ export function referencesEdits(value, owner, target) {
 /** The class an `entity: () => Post` getter returns, as written. */
 export function entityGetterTarget(relation) {
     const getter = propertyValue(relation, 'entity');
-    return getter && ts.isArrowFunction(getter) && ts.isIdentifier(getter.body) ? getter.body.text : undefined;
+    return getter && ts.isArrowFunction(getter) ? identifierText(getter.body) : undefined;
 }
 /** A column-list entry, its name read off the refs: an expression, or a `column` given otherwise, has none. */
 function keyListEntryEdits(entry, param) {

package/dist/statementSql.d.ts

@@ -0,0 +1,7 @@
+import ts from 'typescript';
+/**
+ * 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;

package/dist/statementSql.js

@@ -0,0 +1,53 @@
+import ts from 'typescript';
+import { templateOf } 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 `$`.
+ */
+const SQL_TOKEN = /('(?:[^']|'')*'|"(?:[^"]|"")*"|`[^`]*`|--[^\n]*|\/\*[\s\S]*?\*\/)|(\?)|\$([1-9]\d*)|[$\\#'"`]|\/\*/g;
+/** `sql` split at its placeholders where they are all `?` or all `$n` and bind exactly `count` values. */
+function placeholdersOf(sql, count) {
+    const texts = [];
+    const values = [];
+    const styles = new Set();
+    let from = 0;
+    for (const { 0: token, 1: skipped, 2: question, 3: position, index } of sql.matchAll(SQL_TOKEN)) {
+        if (skipped !== undefined) {
+            if (/\?|\$\d/.test(skipped)) {
+                return undefined;
+            }
+            continue;
+        }
+        if (!question && !position) {
+            return undefined;
+        }
+        styles.add(question ? '?' : '$');
+        values.push(position ? Number(position) - 1 : values.length);
+        texts.push(sql.slice(from, index));
+        from = index + token.length;
+    }
+    texts.push(sql.slice(from));
+    const exact = new Set(values).size === count && values.every((value) => value < count);
+    return styles.size <= 1 && exact ? { texts, values } : undefined;
+}
+/**
+ * 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 function statementTemplate(sql, values) {
+    if (!ts.isStringLiteral(sql) && !ts.isNoSubstitutionTemplateLiteral(sql)) {
+        return undefined;
+    }
+    if (!values.length) {
+        return templateOf([sql.text]);
+    }
+    const [list] = values;
+    const elements = ts.isArrayLiteralExpression(list) ? list.elements : undefined;
+    if (values.length > 1 || !elements || elements.some((it) => ts.isSpreadElement(it) || ts.isOmittedExpression(it))) {
+        return undefined;
+    }
+    const placeholders = placeholdersOf(sql.text, elements.length);
+    return (placeholders &&
+        templateOf(placeholders.texts, placeholders.values.map((at) => elements[at].getText())));
+}

package/dist/syntax.d.ts

@@ -0,0 +1,22 @@
+import ts from 'typescript';
+/** The text of `node` where it is an identifier. */
+export declare function identifierText(node: ts.Node | undefined): string | undefined;
+/** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
+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;
+/** The property `name` of an object literal, a shorthand included. */
+export declare function namedProperty(node: ts.ObjectLiteralExpression, name: string): NamedProperty | undefined;
+/** 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 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;
+/** 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;

package/dist/syntax.js

@@ -0,0 +1,41 @@
+import ts from 'typescript';
+/** The text of `node` where it is an identifier. */
+export function identifierText(node) {
+    return node && ts.isIdentifier(node) ? node.text : undefined;
+}
+/** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
+export function propertyKey(name) {
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+/** The property `name` of an object literal, a shorthand included. */
+export function namedProperty(node, name) {
+    return node.properties.find((prop) => (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) && propertyKey(prop.name) === name);
+}
+/** The property `name` of an object literal that is written with a value. */
+export function propertyAssignment(node, name) {
+    return node.properties.find((prop) => ts.isPropertyAssignment(prop) && propertyKey(prop.name) === name);
+}
+export function propertyValue(node, name) {
+    return propertyAssignment(node, name)?.initializer;
+}
+/** The property assignments of an object literal, or none where `node` is not one. */
+export function objectProperties(node) {
+    return node && ts.isObjectLiteralExpression(node) ? node.properties.filter(ts.isPropertyAssignment) : [];
+}
+/** The elements of an array literal, or none where `node` is not one. */
+export function arrayElements(node) {
+    return node && ts.isArrayLiteralExpression(node) ? node.elements : [];
+}
+/** `node` where it is an object literal. */
+export function objectLiteral(node) {
+    return node && ts.isObjectLiteralExpression(node) ? node : undefined;
+}
+/** A node's decorators, or none where it is a kind that cannot carry them. */
+export function decoratorsOf(node) {
+    return ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
+}
+/** `Field` for `@Field` and `@Field(...)`. */
+export function decoratorName(node) {
+    const { expression } = node;
+    return identifierText(ts.isCallExpression(expression) ? expression.expression : expression);
+}

package/dist/transform.d.ts

@@ -8,7 +8,10 @@ export type FileResult = {
     /** Rewrites that are correct but worth a second look. */
     readonly notes: readonly string[];
 };
-/** Rewrites one source file for the standard decorator spec. */
+/**
+ * Rewrites one source file for the standard decorator spec. The builder's and querier's methods are known by
+ * name, so they are read only in a file importing uql-orm, and `expr` only where it is uql's.
+ */
 export declare function transformFile(source: ts.SourceFile, checker: ts.TypeChecker, options?: {
     readonly strictNullChecks: boolean;
 }): FileResult;