@pgsql/transform 18.3.1 → 18.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.3.1",
+  "version": "18.4.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "AST-based SQL transformation, qualification, classification and closure analysis for PostgreSQL",
   "main": "index.js",
@@ -49,5 +49,5 @@
     "classify",
     "plpgsql"
   ],
-  "gitHead": "ef29a3eb49d020f309f7289dbf1fd1e642ed5008"
+  "gitHead": "df667707ab725d762cac0daab26a07d1b202d1e1"
 }

package/router.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Schema routing for the core transform.
+ *
+ * The schema transform historically rewrote every reference to a source
+ * schema to a single target schema (`Map<oldSchema, newSchema>`). That is the
+ * degenerate, whole-schema case of a more general question asked at every
+ * schema-qualified occurrence:
+ *
+ *   given a reference to `(schema, name)` in namespace `ns`, what schema
+ *   should it live in now?
+ *
+ * A {@link SchemaRouter} answers exactly that. It unifies two dimensions:
+ *
+ * - **schema-level** default: move everything in a source schema to one target
+ *   (the classic `Map` behaviour), and
+ * - **object-level** routes: send a specific object — a table, a function, a
+ *   type — to its own target schema, independent of its siblings.
+ *
+ * Object routes are bucketed by PostgreSQL namespace (`relations`, `functions`,
+ * `types` — matching `pg_class` / `pg_proc` / `pg_type`), mirroring the routing
+ * model already used by {@link qualifyUnqualified}. Resolution is
+ * object-route-first, then the schema-level default, then "leave unchanged".
+ */
+/** PostgreSQL object namespaces relevant to schema routing. */
+export type ObjectNamespace = 'relation' | 'function' | 'type';
+/**
+ * A namespace hint for a schema-qualified occurrence. `schema` marks an
+ * operation on the schema itself (CREATE/DROP/GRANT ON SCHEMA, search_path);
+ * `unknown` marks a site whose namespace cannot be determined statically, in
+ * which case only the schema-level default applies.
+ */
+export type RouteNamespace = ObjectNamespace | 'schema' | 'unknown';
+/** Per-source-schema routing: a schema-level default plus per-object routes. */
+export interface SchemaRoute {
+    /**
+     * Schema-level default: every object in this source schema that has no more
+     * specific object route moves here. Omit to route *only* the named objects
+     * and leave the rest (and the schema itself) untouched.
+     */
+    schema?: string;
+    /** Relation name (table/view/sequence/matview) → target schema. */
+    relations?: Record<string, string>;
+    /** Function/procedure/aggregate name → target schema. */
+    functions?: Record<string, string>;
+    /** Type/domain name → target schema. */
+    types?: Record<string, string>;
+}
+/** The full routing specification: one {@link SchemaRoute} per source schema. */
+export type RouteSpec = Record<string, SchemaRoute>;
+/**
+ * Resolves the target schema for any schema-qualified occurrence, unifying the
+ * whole-schema `Map` behaviour and per-object routing behind one `resolve`.
+ */
+export declare class SchemaRouter {
+    private readonly routes;
+    constructor(routes?: RouteSpec | Map<string, SchemaRoute>);
+    /** Build a router from the classic whole-schema `Map<oldSchema,newSchema>`. */
+    static fromSchemaMap(mapping: Map<string, string> | Record<string, string>): SchemaRouter;
+    /** Coerce a `Map`, plain mapping, or existing router into a router. */
+    static from(source: SchemaRouter | Map<string, string> | Record<string, string>): SchemaRouter;
+    /** True when this router might rewrite something in `sourceSchema`. */
+    has(sourceSchema: string | undefined | null): boolean;
+    /** True when the router carries no routes at all. */
+    get size(): number;
+    /**
+     * True when any route targets individual objects (as opposed to whole
+     * schemas). Object routes require AST-precise rewriting of opaque function
+     * bodies; whole-schema routes are handled by the cheaper string passes.
+     */
+    hasObjectRoutes(): boolean;
+    /** Every source schema this router may touch. */
+    sourceSchemas(): string[];
+    /**
+     * Resolve the target schema for `(sourceSchema, name)` in namespace `ns`,
+     * or `undefined` to leave it unchanged. Object routes win over the
+     * schema-level default; the default applies to schema-level operations and
+     * to any object without a specific route.
+     */
+    resolve(sourceSchema: string | undefined | null, name?: string, ns?: RouteNamespace): string | undefined;
+    /**
+     * Source schemas whose *every* object is guaranteed to move — i.e. those
+     * with a schema-level default. After a transform, none of these should
+     * survive as a qualifier; partially-routed schemas may legitimately remain,
+     * so they are excluded from the strict leftover check.
+     */
+    fullyMovedSchemas(): Map<string, string>;
+    /**
+     * A flat schema-level view (`oldSchema → newSchema`) for legacy string-level
+     * passes and comment/verify/JSON rewrites that operate per source schema.
+     * Only schema-level defaults are included; object-only routes carry no single
+     * schema answer and are omitted.
+     */
+    schemaLevelMap(): Map<string, string>;
+}

package/router.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Schema routing for the core transform.
+ *
+ * The schema transform historically rewrote every reference to a source
+ * schema to a single target schema (`Map<oldSchema, newSchema>`). That is the
+ * degenerate, whole-schema case of a more general question asked at every
+ * schema-qualified occurrence:
+ *
+ *   given a reference to `(schema, name)` in namespace `ns`, what schema
+ *   should it live in now?
+ *
+ * A {@link SchemaRouter} answers exactly that. It unifies two dimensions:
+ *
+ * - **schema-level** default: move everything in a source schema to one target
+ *   (the classic `Map` behaviour), and
+ * - **object-level** routes: send a specific object — a table, a function, a
+ *   type — to its own target schema, independent of its siblings.
+ *
+ * Object routes are bucketed by PostgreSQL namespace (`relations`, `functions`,
+ * `types` — matching `pg_class` / `pg_proc` / `pg_type`), mirroring the routing
+ * model already used by {@link qualifyUnqualified}. Resolution is
+ * object-route-first, then the schema-level default, then "leave unchanged".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaRouter = void 0;
+const NS_BUCKET = {
+    relation: 'relations',
+    function: 'functions',
+    type: 'types'
+};
+/**
+ * Resolves the target schema for any schema-qualified occurrence, unifying the
+ * whole-schema `Map` behaviour and per-object routing behind one `resolve`.
+ */
+class SchemaRouter {
+    routes;
+    constructor(routes = {}) {
+        this.routes = routes instanceof Map ? new Map(routes) : new Map(Object.entries(routes));
+    }
+    /** Build a router from the classic whole-schema `Map<oldSchema,newSchema>`. */
+    static fromSchemaMap(mapping) {
+        const entries = mapping instanceof Map ? [...mapping.entries()] : Object.entries(mapping);
+        const spec = {};
+        for (const [from, to] of entries)
+            spec[from] = { schema: to };
+        return new SchemaRouter(spec);
+    }
+    /** Coerce a `Map`, plain mapping, or existing router into a router. */
+    static from(source) {
+        if (source instanceof SchemaRouter)
+            return source;
+        return SchemaRouter.fromSchemaMap(source);
+    }
+    /** True when this router might rewrite something in `sourceSchema`. */
+    has(sourceSchema) {
+        if (!sourceSchema)
+            return false;
+        return this.routes.has(sourceSchema);
+    }
+    /** True when the router carries no routes at all. */
+    get size() {
+        return this.routes.size;
+    }
+    /**
+     * True when any route targets individual objects (as opposed to whole
+     * schemas). Object routes require AST-precise rewriting of opaque function
+     * bodies; whole-schema routes are handled by the cheaper string passes.
+     */
+    hasObjectRoutes() {
+        for (const route of this.routes.values()) {
+            if (route.relations || route.functions || route.types)
+                return true;
+        }
+        return false;
+    }
+    /** Every source schema this router may touch. */
+    sourceSchemas() {
+        return [...this.routes.keys()];
+    }
+    /**
+     * Resolve the target schema for `(sourceSchema, name)` in namespace `ns`,
+     * or `undefined` to leave it unchanged. Object routes win over the
+     * schema-level default; the default applies to schema-level operations and
+     * to any object without a specific route.
+     */
+    resolve(sourceSchema, name, ns = 'unknown') {
+        if (!sourceSchema)
+            return undefined;
+        const route = this.routes.get(sourceSchema);
+        if (!route)
+            return undefined;
+        if (name && (ns === 'relation' || ns === 'function' || ns === 'type')) {
+            const bucket = route[NS_BUCKET[ns]];
+            const mapped = bucket?.[name];
+            if (mapped !== undefined)
+                return mapped;
+        }
+        return route.schema;
+    }
+    /**
+     * Source schemas whose *every* object is guaranteed to move — i.e. those
+     * with a schema-level default. After a transform, none of these should
+     * survive as a qualifier; partially-routed schemas may legitimately remain,
+     * so they are excluded from the strict leftover check.
+     */
+    fullyMovedSchemas() {
+        const out = new Map();
+        for (const [from, route] of this.routes) {
+            if (route.schema !== undefined)
+                out.set(from, route.schema);
+        }
+        return out;
+    }
+    /**
+     * A flat schema-level view (`oldSchema → newSchema`) for legacy string-level
+     * passes and comment/verify/JSON rewrites that operate per source schema.
+     * Only schema-level defaults are included; object-only routes carry no single
+     * schema answer and are omitted.
+     */
+    schemaLevelMap() {
+        return this.fullyMovedSchemas();
+    }
+}
+exports.SchemaRouter = SchemaRouter;

package/transform.d.ts

@@ -24,6 +24,10 @@
  * - Comment headers, verify function calls, JSON string values (regex fallback)
  */
 import type { QualifyUnqualifiedOptions } from './qualify';
+import type { RouteNamespace } from './router';
+import { SchemaRouter } from './router';
+/** A schema mapping accepted by the transform: the classic whole-schema map or a router. */
+export type SchemaMappingInput = Map<string, string> | SchemaRouter;
 export interface SchemaTransformResult {
     schemasFound: Set<string>;
     schemasTransformed: Map<string, string>;
@@ -91,26 +95,31 @@ export declare function shouldTransformSchema(schemaName: string | undefined, sc
 /**
  * Transform schema names in a String node array (used for funcname, names, etc.)
  * These arrays contain String nodes like { String: { sval: 'schema_name' } }
+ *
+ * `ns` names the namespace of the referenced object so object-level routes can
+ * apply; the object's own name is the last element of the list. When `ns` is
+ * `unknown` (the default) only the schema-level default applies — identical to
+ * the historic whole-schema behaviour.
  */
-export declare function transformNameList(names: any[] | undefined, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+export declare function transformNameList(names: any[] | undefined, schemaMapping: SchemaMappingInput, result: SchemaTransformResult, ns?: RouteNamespace): void;
 /**
  * Transform a bare schema-name field on a node (e.g. { String: { sval } }
  * entries in GrantStmt.objects, RenameStmt.subname, CommentStmt.object).
  * Returns the (possibly new) schema name.
  */
-export declare function transformSchemaNameField(container: any, field: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+export declare function transformSchemaNameField(container: any, field: string, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): void;
 /**
  * Transform a RangeVar-like relation object (has schemaname/relname fields).
  * Many statement nodes embed a relation that the walker does NOT auto-recurse into.
  */
-export declare function transformRelation(relation: any, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+export declare function transformRelation(relation: any, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): void;
 /**
  * Transform schema-qualified references embedded in a plain string
  * (e.g. advisory-lock keys like 'schema-name.fn_name', COMMENT text,
  * RAISE messages). Only occurrences of a mapped schema name immediately
  * followed by a dot are rewritten.
  */
-export declare function transformSchemaRefsInString(str: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+export declare function transformSchemaRefsInString(str: string, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): string;
 /**
  * Create a SQL AST visitor that transforms schema names.
  *
@@ -119,7 +128,7 @@ export declare function transformSchemaRefsInString(str: string, schemaMapping:
  * However, some node types carry schema names as plain strings or name lists
  * that require explicit handlers.
  */
-export declare function createSqlVisitor(schemaMapping: Map<string, string>, result: SchemaTransformResult, visitorOptions?: {
+export declare function createSqlVisitor(schemaMapping: SchemaMappingInput, result: SchemaTransformResult, visitorOptions?: {
     assumeSchemasExist?: Set<string>;
 }): {
     RangeVar: (path: any) => void;
@@ -182,27 +191,27 @@ export declare function createSqlVisitor(schemaMapping: Map<string, string>, res
  * Throws an error if any schema names from the mapping are found in the output,
  * indicating that the AST visitor is missing a handler for that node type.
  */
-export declare function validateNoUntransformedSchemas(content: string, schemaMapping: Map<string, string>): void;
+export declare function validateNoUntransformedSchemas(content: string, schemaMapping: SchemaMappingInput): void;
 /**
  * Create a PL/pgSQL visitor that transforms schema names in PL/pgSQL-specific nodes.
  */
-export declare function createPlpgsqlVisitor(schemaMapping: Map<string, string>, result: SchemaTransformResult): {
+export declare function createPlpgsqlVisitor(schemaMapping: SchemaMappingInput, result: SchemaTransformResult): {
     PLpgSQL_type: (path: any) => void;
     PLpgSQL_var: (path: any) => void;
 };
 /**
  * Transform a PLpgSQL_type typname using proper AST parsing.
  */
-export declare function transformPlpgsqlTypeAst(typname: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+export declare function transformPlpgsqlTypeAst(typname: string, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): string;
 /**
  * Fallback string-based transformation for PLpgSQL_type typname.
  * Uses @pgsql/quotes QuoteUtils for proper identifier quoting.
  */
-export declare function transformPlpgsqlTypeString(typname: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+export declare function transformPlpgsqlTypeString(typname: string, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): string;
 /**
  * Recursively walk the PL/pgSQL AST to transform schema names.
  */
-export declare function walkPlpgsqlForSchemas(node: any, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+export declare function walkPlpgsqlForSchemas(node: any, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): void;
 /**
  * Escape a string for use in a regular expression
  */
@@ -244,7 +253,7 @@ export declare function transformJsonStringValues(content: string, schemaMapping
  * `options.post_passes`.  The built-in passes `transform_verify_calls`
  * and `transform_json_string_values` are exported for convenience.
  */
-export declare function transformSql(content: string, schemaMapping: Map<string, string>, options?: TransformSqlOptions | SchemaTransformResult, result?: SchemaTransformResult): {
+export declare function transformSql(content: string, schemaMapping: SchemaMappingInput, options?: TransformSqlOptions | SchemaTransformResult, result?: SchemaTransformResult): {
     content: string;
     result: SchemaTransformResult;
 };
@@ -253,7 +262,7 @@ export declare function transformSql(content: string, schemaMapping: Map<string,
  * Unlike transform_sql, this does NOT handle headers, verify calls, or JSON values.
  * Use this for testing individual SQL statements.
  */
-export declare function transformSqlStatement(sql: string, schemaMapping: Map<string, string>, result?: SchemaTransformResult): {
+export declare function transformSqlStatement(sql: string, schemaMapping: SchemaMappingInput, result?: SchemaTransformResult): {
     sql: string;
     result: SchemaTransformResult;
 };