@pgsql/transform 18.6.0 → 18.7.0

package/esm/router.js

@@ -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.
  */
 const NS_BUCKET = {
     relation: 'relations',
@@ -71,6 +84,36 @@ export 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()];
@@ -82,18 +125,39 @@ export 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/esm/transform.js

@@ -80,12 +80,24 @@ export function transformNameList(names, schemaMapping, result, ns = 'unknown')
     const first = names[0];
     if (first?.String?.sval) {
         const schemaName = first.String.sval;
-        const objName = names[names.length - 1]?.String?.sval;
-        const newName = router.resolve(schemaName, objName, ns);
-        if (newName && newName !== schemaName) {
+        const last = names[names.length - 1];
+        const objName = last?.String?.sval;
+        const target = router.resolveObject(schemaName, objName, ns);
+        if (!target)
+            return;
+        if (target.name !== undefined && last?.String?.sval) {
             result.schemasFound.add(schemaName);
-            first.String.sval = newName;
-            result.schemasTransformed.set(schemaName, newName);
+            last.String.sval = target.name;
+        }
+        if (target.schema === null) {
+            // De-qualify: drop the schema element and rely on search_path.
+            result.schemasFound.add(schemaName);
+            names.splice(0, 1);
+        }
+        else if (target.schema && target.schema !== schemaName) {
+            result.schemasFound.add(schemaName);
+            first.String.sval = target.schema;
+            result.schemasTransformed.set(schemaName, target.schema);
         }
     }
 }
@@ -117,11 +129,22 @@ export function transformRelation(relation, schemaMapping, result) {
     const oldName = relation.schemaname;
     // A RangeVar names a relation (table/view/sequence/matview); route by the
     // relation name so object-level routes can send it to its own schema.
-    const newName = asRouter(schemaMapping).resolve(oldName, relation.relname, 'relation');
-    if (newName && newName !== oldName) {
+    const target = asRouter(schemaMapping).resolveObject(oldName, relation.relname, 'relation');
+    if (!target)
+        return;
+    if (target.name !== undefined && relation.relname) {
+        result.schemasFound.add(oldName);
+        relation.relname = target.name;
+    }
+    if (target.schema === null) {
+        // De-qualify: drop the schema qualifier and rely on search_path.
+        result.schemasFound.add(oldName);
+        delete relation.schemaname;
+    }
+    else if (target.schema && target.schema !== oldName) {
         result.schemasFound.add(oldName);
-        relation.schemaname = newName;
-        result.schemasTransformed.set(oldName, newName);
+        relation.schemaname = target.schema;
+        result.schemasTransformed.set(oldName, target.schema);
     }
 }
 /**

package/index.d.ts

@@ -10,7 +10,7 @@ export type { RoleTransformResult } from './role-transform';
 export { createRoleResult, createRoleVisitor, transformRoles, } from './role-transform';
 export type { ObjectInventory, QualifyResult, QualifyRoutes, QualifyTargetSelector, QualifyUnqualifiedOptions, } from './qualify';
 export { collectCreatedObjects, createQualifyVisitor, mergeInventories, qualifyUnqualified, } from './qualify';
-export type { ObjectNamespace, RouteNamespace, RouteSpec, SchemaRoute, } from './router';
+export type { ObjectNamespace, ObjectRoute, ObjectRouteTarget, RouteNamespace, RouteSpec, SchemaRoute, } from './router';
 export { SchemaRouter } from './router';
 export type { CapturedAsts } from './round-trip';
 export { captureAstsFromSql, captureTransformAsts, firstDifference, normalizeParseTree, validateRoundTrip, } from './round-trip';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.6.0",
+  "version": "18.7.0",
   "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": "6d3c28348fab5cace76f7c0167f3b73e8f9f67c8"
+  "gitHead": "057e427849438bfea946d6d85557603ba7fea134"
 }

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.js

@@ -101,12 +101,24 @@ function transformNameList(names, schemaMapping, result, ns = 'unknown') {
     const first = names[0];
     if (first?.String?.sval) {
         const schemaName = first.String.sval;
-        const objName = names[names.length - 1]?.String?.sval;
-        const newName = router.resolve(schemaName, objName, ns);
-        if (newName && newName !== schemaName) {
+        const last = names[names.length - 1];
+        const objName = last?.String?.sval;
+        const target = router.resolveObject(schemaName, objName, ns);
+        if (!target)
+            return;
+        if (target.name !== undefined && last?.String?.sval) {
             result.schemasFound.add(schemaName);
-            first.String.sval = newName;
-            result.schemasTransformed.set(schemaName, newName);
+            last.String.sval = target.name;
+        }
+        if (target.schema === null) {
+            // De-qualify: drop the schema element and rely on search_path.
+            result.schemasFound.add(schemaName);
+            names.splice(0, 1);
+        }
+        else if (target.schema && target.schema !== schemaName) {
+            result.schemasFound.add(schemaName);
+            first.String.sval = target.schema;
+            result.schemasTransformed.set(schemaName, target.schema);
         }
     }
 }
@@ -138,11 +150,22 @@ function transformRelation(relation, schemaMapping, result) {
     const oldName = relation.schemaname;
     // A RangeVar names a relation (table/view/sequence/matview); route by the
     // relation name so object-level routes can send it to its own schema.
-    const newName = asRouter(schemaMapping).resolve(oldName, relation.relname, 'relation');
-    if (newName && newName !== oldName) {
+    const target = asRouter(schemaMapping).resolveObject(oldName, relation.relname, 'relation');
+    if (!target)
+        return;
+    if (target.name !== undefined && relation.relname) {
+        result.schemasFound.add(oldName);
+        relation.relname = target.name;
+    }
+    if (target.schema === null) {
+        // De-qualify: drop the schema qualifier and rely on search_path.
+        result.schemasFound.add(oldName);
+        delete relation.schemaname;
+    }
+    else if (target.schema && target.schema !== oldName) {
         result.schemasFound.add(oldName);
-        relation.schemaname = newName;
-        result.schemasTransformed.set(oldName, newName);
+        relation.schemaname = target.schema;
+        result.schemasTransformed.set(oldName, target.schema);
     }
 }
 /**