@pgsql/transform 18.6.0 → 18.8.0

package/router.d.ts

@@ -20,6 +20,19 @@
  * `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".
+ *
+ * An object route may also *rebind* — change the object's **name**, not just
+ * the schema it lives in. Routing preserves identity (the same function, a new
+ * address); rebinding repoints a reference at a *different* object, which is
+ * what lets one implementation of a contract be substituted for another:
+ *
+ * ```ts
+ * { auth: { functions: { uid: { schema: null, name: 'current_user_id' } } } }
+ * // auth.uid()  ->  current_user_id()
+ * ```
+ *
+ * A `null` target schema de-qualifies the reference (relying on `search_path`),
+ * matching the convention used by the extension router.
  */
 /** PostgreSQL object namespaces relevant to schema routing. */
 export type ObjectNamespace = 'relation' | 'function' | 'type';
@@ -30,6 +43,24 @@ export type ObjectNamespace = 'relation' | 'function' | 'type';
  * which case only the schema-level default applies.
  */
 export type RouteNamespace = ObjectNamespace | 'schema' | 'unknown';
+/**
+ * Where a specific object should be reached instead. Either field may be
+ * omitted: omitting `schema` keeps the schema-level default (or the current
+ * schema when the route has none), and omitting `name` keeps the object's own
+ * name — so `{ name }` alone is a pure rebind and `{ schema }` alone is
+ * equivalent to the shorthand string form.
+ */
+export interface ObjectRoute {
+    /** Target schema, or `null` to make the reference unqualified. */
+    schema?: string | null;
+    /** Target object name — rebinds the reference to a different object. */
+    name?: string;
+}
+/**
+ * An object route target. The shorthand `string` form is the target schema,
+ * identical to `{ schema: target }`.
+ */
+export type ObjectRouteTarget = string | ObjectRoute;
 /** Per-source-schema routing: a schema-level default plus per-object routes. */
 export interface SchemaRoute {
     /**
@@ -38,12 +69,12 @@ export interface SchemaRoute {
      * 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>;
+    /** Relation name (table/view/sequence/matview) → target schema or rebind. */
+    relations?: Record<string, ObjectRouteTarget>;
+    /** Function/procedure/aggregate name → target schema or rebind. */
+    functions?: Record<string, ObjectRouteTarget>;
+    /** Type/domain name → target schema or rebind. */
+    types?: Record<string, ObjectRouteTarget>;
 }
 /** The full routing specification: one {@link SchemaRoute} per source schema. */
 export type RouteSpec = Record<string, SchemaRoute>;
@@ -68,6 +99,22 @@ export declare class SchemaRouter {
      * bodies; whole-schema routes are handled by the cheaper string passes.
      */
     hasObjectRoutes(): boolean;
+    /**
+     * True when any object route changes a name or de-qualifies (rather than
+     * only moving between schemas). Such rewrites cannot be expressed by the
+     * string-level passes at all, so callers use this to require the AST path.
+     */
+    hasNameRebinds(): boolean;
+    /**
+     * Every object route that rebinds a name or de-qualifies, keyed by source
+     * schema and namespace. Callers use this to report or verify substitutions.
+     */
+    nameRebinds(): Array<{
+        schema: string;
+        ns: ObjectNamespace;
+        from: string;
+        to: ObjectRoute;
+    }>;
     /** Every source schema this router may touch. */
     sourceSchemas(): string[];
     /**
@@ -77,6 +124,16 @@ export declare class SchemaRouter {
      * to any object without a specific route.
      */
     resolve(sourceSchema: string | undefined | null, name?: string, ns?: RouteNamespace): string | undefined;
+    /**
+     * Resolve the full target for `(sourceSchema, name)` in namespace `ns` — both
+     * the schema the reference should live in and, when the route rebinds, the
+     * name it should be reached by. Returns `undefined` to leave it unchanged.
+     *
+     * In the result, `schema` is `null` when the reference should become
+     * unqualified and `undefined` when only the name changes; `name` is
+     * `undefined` when only the schema changes.
+     */
+    resolveObject(sourceSchema: string | undefined | null, name?: string, ns?: RouteNamespace): ObjectRoute | 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

package/router.js

@@ -21,6 +21,19 @@
  * `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".
+ *
+ * An object route may also *rebind* — change the object's **name**, not just
+ * the schema it lives in. Routing preserves identity (the same function, a new
+ * address); rebinding repoints a reference at a *different* object, which is
+ * what lets one implementation of a contract be substituted for another:
+ *
+ * ```ts
+ * { auth: { functions: { uid: { schema: null, name: 'current_user_id' } } } }
+ * // auth.uid()  ->  current_user_id()
+ * ```
+ *
+ * A `null` target schema de-qualifies the reference (relying on `search_path`),
+ * matching the convention used by the extension router.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchemaRouter = void 0;
@@ -74,6 +87,36 @@ class SchemaRouter {
         }
         return false;
     }
+    /**
+     * True when any object route changes a name or de-qualifies (rather than
+     * only moving between schemas). Such rewrites cannot be expressed by the
+     * string-level passes at all, so callers use this to require the AST path.
+     */
+    hasNameRebinds() {
+        return this.nameRebinds().length > 0;
+    }
+    /**
+     * Every object route that rebinds a name or de-qualifies, keyed by source
+     * schema and namespace. Callers use this to report or verify substitutions.
+     */
+    nameRebinds() {
+        const out = [];
+        for (const [schema, route] of this.routes) {
+            for (const ns of ['relation', 'function', 'type']) {
+                const bucket = route[NS_BUCKET[ns]];
+                if (!bucket)
+                    continue;
+                for (const [from, target] of Object.entries(bucket)) {
+                    if (typeof target === 'string')
+                        continue;
+                    if (target.name === undefined && target.schema !== null)
+                        continue;
+                    out.push({ schema, ns, from, to: target });
+                }
+            }
+        }
+        return out;
+    }
     /** Every source schema this router may touch. */
     sourceSchemas() {
         return [...this.routes.keys()];
@@ -85,18 +128,39 @@ class SchemaRouter {
      * to any object without a specific route.
      */
     resolve(sourceSchema, name, ns = 'unknown') {
+        // A `null` target de-qualifies the reference; the schema-only API cannot
+        // express that, so it reads as "unchanged" here.
+        return this.resolveObject(sourceSchema, name, ns)?.schema ?? undefined;
+    }
+    /**
+     * Resolve the full target for `(sourceSchema, name)` in namespace `ns` — both
+     * the schema the reference should live in and, when the route rebinds, the
+     * name it should be reached by. Returns `undefined` to leave it unchanged.
+     *
+     * In the result, `schema` is `null` when the reference should become
+     * unqualified and `undefined` when only the name changes; `name` is
+     * `undefined` when only the schema changes.
+     */
+    resolveObject(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;
+            const target = route[NS_BUCKET[ns]]?.[name];
+            if (target !== undefined) {
+                if (typeof target === 'string')
+                    return { schema: target };
+                // An object route naming no schema inherits the schema-level default,
+                // so a pure rebind leaves placement alone.
+                return {
+                    schema: target.schema !== undefined ? target.schema : route.schema,
+                    name: target.name
+                };
+            }
         }
-        return route.schema;
+        return route.schema !== undefined ? { schema: route.schema } : undefined;
     }
     /**
      * Source schemas whose *every* object is guaranteed to move — i.e. those

package/transform.d.ts

@@ -110,7 +110,10 @@ export declare function transformNameList(names: any[] | undefined, schemaMappin
 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.
+ * The walker auto-recurses into embedded relations (concrete `RangeVar`
+ * fields are tag-synthesized), so the generic `RangeVar` visitor covers
+ * every occurrence; statement handlers call this directly only when they
+ * carry extra context, and the claim guard keeps each relation routed once.
  */
 export declare function transformRelation(relation: any, schemaMapping: SchemaMappingInput, result: SchemaTransformResult): void;
 /**
@@ -134,34 +137,13 @@ export declare function createSqlVisitor(schemaMapping: SchemaMappingInput, resu
     RangeVar: (path: any) => void;
     CreateSchemaStmt: (path: any) => void;
     FuncCall: (path: any) => void;
-    CallStmt: (path: any) => void;
     TypeName: (path: any) => void;
     ColumnRef: (path: any) => void;
     GrantStmt: (path: any) => void;
     VariableSetStmt: (path: any) => void;
     AlterDefaultPrivilegesStmt: (path: any) => void;
     DropStmt: (path: any) => void;
-    InsertStmt: (path: any) => void;
-    CreateStmt: (path: any) => void;
-    UpdateStmt: (path: any) => void;
-    DeleteStmt: (path: any) => void;
-    MergeStmt: (path: any) => void;
-    IndexStmt: (path: any) => void;
-    Constraint: (path: any) => void;
-    CompositeTypeStmt: (path: any) => void;
-    ColumnDef: (path: any) => void;
-    ViewStmt: (path: any) => void;
-    AlterTableStmt: (path: any) => void;
-    CreateSeqStmt: (path: any) => void;
     AlterSeqStmt: (path: any) => void;
-    CreatePolicyStmt: (path: any) => void;
-    RuleStmt: (path: any) => void;
-    CopyStmt: (path: any) => void;
-    ClusterStmt: (path: any) => void;
-    VacuumRelation: (path: any) => void;
-    RefreshMatViewStmt: (path: any) => void;
-    CreateTableAsStmt: (path: any) => void;
-    TypeCast: (path: any) => void;
     CreateFunctionStmt: (path: any) => void;
     CreateTrigStmt: (path: any) => void;
     CommentStmt: (path: any) => void;