@pgsql/transform 18.9.0 → 18.10.0

package/esm/index.js

@@ -1,5 +1,6 @@
 export { classifyStatements } from './facts';
 export { buildStatementGraph } from './graph';
+export { identityOf } from './naming';
 export { orderStatements, restructureSql } from './restructure';
 export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
 export { createExtensionResult, createExtensionVisitor, transformExtensions, } from './extension-transform';

package/esm/naming.js

@@ -0,0 +1,65 @@
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+export function identityOf(facts) {
+    if (facts.kind === 'extension' && facts.extension) {
+        return { kind: 'extension', schema: null, name: facts.extension.name };
+    }
+    const created = facts.creates[0];
+    if (!created)
+        return null;
+    switch (facts.kind) {
+        case 'schema':
+            return { kind: 'schema', schema: null, name: created.name };
+        case 'trigger':
+        case 'policy': {
+            const dot = created.name.indexOf('.');
+            if (dot > 0) {
+                return {
+                    kind: facts.kind,
+                    schema: created.schema,
+                    name: created.name.slice(dot + 1),
+                    table: created.name.slice(0, dot)
+                };
+            }
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        }
+        case 'index': {
+            // IndexStmt records the index name in creates and the indexed relation
+            // in references (same-schema RangeVar).
+            const rel = facts.references.find(r => r.schema === created.schema) ?? facts.references[0];
+            return {
+                kind: 'index',
+                schema: created.schema,
+                name: created.name,
+                table: rel?.name
+            };
+        }
+        case 'fk_constraint':
+        case 'constraint':
+        case 'rls_enable':
+            // ALTER TABLE statements target their table.
+            return { kind: 'constraint', schema: created.schema, name: created.name, table: created.name };
+        case 'seed_dml':
+            return { kind: 'seed_dml', schema: created.schema, name: created.name, table: created.name };
+        case 'table':
+            // AlterTableStmt facts also classify as `table`-targeting; the created
+            // name is the table either way.
+            return { kind: 'table', schema: created.schema, name: created.name };
+        case 'view':
+        case 'function':
+        case 'type':
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        default:
+            if (facts.nodeTag === 'CreateSeqStmt') {
+                return { kind: 'sequence', schema: created.schema, name: created.name };
+            }
+            return { kind: 'other', schema: created.schema, name: created.name };
+    }
+}

package/index.d.ts

@@ -2,6 +2,8 @@ export type { ExtensionAction, ExtensionFact, QualifiedName, StatementFacts, Sta
 export { classifyStatements } from './facts';
 export type { EdgeKind, StatementEdge, StatementGraph, StatementNode, } from './graph';
 export { buildStatementGraph } from './graph';
+export type { ObjectIdentity, ObjectIdentityKind, } from './naming';
+export { identityOf } from './naming';
 export type { Granularity, RestructureOptions, RestructureResult, } from './restructure';
 export { orderStatements, restructureSql } from './restructure';
 export type { ExtensionDefinition, ExtensionRoute, ExtensionRouteSpec, ExtensionRouterOptions, ExtensionSymbol, ExtensionSymbolNamespace, SymbolRewrite, } from './extension-router';

package/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.walkPlpgsqlForSchemas = exports.validateNoUntransformedSchemas = exports.transformVerifyCalls = exports.transformSqlStatement = exports.transformSql = exports.transformSchemaName = exports.transformRelation = exports.transformPlpgsqlTypeString = exports.transformPlpgsqlTypeAst = exports.transformNameList = exports.transformJsonStringValues = exports.transformComments = exports.shouldTransformSchema = exports.extractPgpmHeader = exports.escapeRegexp = exports.createSqlVisitor = exports.createPlpgsqlVisitor = exports.trimDefElemBody = exports.normalizeTree = exports.cleanTree = exports.CLEAN_TREE_VOLATILE_KEYS = exports.validateRoundTrip = exports.normalizeParseTree = exports.firstDifference = exports.captureTransformAsts = exports.captureAstsFromSql = exports.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.transformRoles = exports.createRoleVisitor = exports.createRoleResult = exports.RoleRouter = exports.transformExtensions = exports.createExtensionVisitor = exports.createExtensionResult = exports.ExtensionRouter = exports.COMMON_EXTENSIONS = exports.restructureSql = exports.orderStatements = exports.buildStatementGraph = exports.classifyStatements = void 0;
+exports.walkPlpgsqlForSchemas = exports.validateNoUntransformedSchemas = exports.transformVerifyCalls = exports.transformSqlStatement = exports.transformSql = exports.transformSchemaName = exports.transformRelation = exports.transformPlpgsqlTypeString = exports.transformPlpgsqlTypeAst = exports.transformNameList = exports.transformJsonStringValues = exports.transformComments = exports.shouldTransformSchema = exports.extractPgpmHeader = exports.escapeRegexp = exports.createSqlVisitor = exports.createPlpgsqlVisitor = exports.trimDefElemBody = exports.normalizeTree = exports.cleanTree = exports.CLEAN_TREE_VOLATILE_KEYS = exports.validateRoundTrip = exports.normalizeParseTree = exports.firstDifference = exports.captureTransformAsts = exports.captureAstsFromSql = exports.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.transformRoles = exports.createRoleVisitor = exports.createRoleResult = exports.RoleRouter = exports.transformExtensions = exports.createExtensionVisitor = exports.createExtensionResult = exports.ExtensionRouter = exports.COMMON_EXTENSIONS = exports.restructureSql = exports.orderStatements = exports.identityOf = exports.buildStatementGraph = exports.classifyStatements = void 0;
 var facts_1 = require("./facts");
 Object.defineProperty(exports, "classifyStatements", { enumerable: true, get: function () { return facts_1.classifyStatements; } });
 var graph_1 = require("./graph");
 Object.defineProperty(exports, "buildStatementGraph", { enumerable: true, get: function () { return graph_1.buildStatementGraph; } });
+var naming_1 = require("./naming");
+Object.defineProperty(exports, "identityOf", { enumerable: true, get: function () { return naming_1.identityOf; } });
 var restructure_1 = require("./restructure");
 Object.defineProperty(exports, "orderStatements", { enumerable: true, get: function () { return restructure_1.orderStatements; } });
 Object.defineProperty(exports, "restructureSql", { enumerable: true, get: function () { return restructure_1.restructureSql; } });

package/naming.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Object identity — the canonical, Postgres-native answer to "what object is
+ * this statement about?".
+ *
+ * Identity is the key used by dependency graphs, semantic diffing, and any
+ * downstream naming scheme. It is a pure function of classifier facts —
+ * grounded in the parser's node taxonomy (`CreateStmt`, `CreateTrigStmt`,
+ * `IndexStmt`, ...), never in surface syntax like RangeVars. Rendering an
+ * identity to a change path (e.g. a pgpm module layout) is deliberately NOT
+ * defined here: paths are derived projections that belong to whichever
+ * packaging layer consumes the identity, so nothing is ever attached to them.
+ *
+ * Identity tuple: `(kind, schema, name, table?)` — `table` scopes objects
+ * that are only unique per table (triggers, policies, indexes, constraints,
+ * seed data). Function overloads share an identity for now (signature
+ * disambiguation is a planned refinement).
+ */
+import { StatementFacts } from './facts';
+/** The kinds of objects an identity can describe. */
+export type ObjectIdentityKind = 'schema' | 'extension' | 'role' | 'table' | 'view' | 'sequence' | 'type' | 'function' | 'index' | 'trigger' | 'policy' | 'constraint' | 'seed_dml' | 'other';
+/**
+ * The identity of a database object. Identity is the diff/dependency key;
+ * any path or name is only a downstream rendering of it.
+ */
+export interface ObjectIdentity {
+    kind: ObjectIdentityKind;
+    /** Owning schema (`null` for non-schema objects: roles, extensions). */
+    schema: string | null;
+    /** Object name, unqualified (for table-scoped kinds: without the table). */
+    name: string;
+    /** Owning table, for objects only unique per table (trigger/policy/index/constraint/seed). */
+    table?: string;
+}
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+export declare function identityOf(facts: StatementFacts): ObjectIdentity | null;

package/naming.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityOf = identityOf;
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+function identityOf(facts) {
+    if (facts.kind === 'extension' && facts.extension) {
+        return { kind: 'extension', schema: null, name: facts.extension.name };
+    }
+    const created = facts.creates[0];
+    if (!created)
+        return null;
+    switch (facts.kind) {
+        case 'schema':
+            return { kind: 'schema', schema: null, name: created.name };
+        case 'trigger':
+        case 'policy': {
+            const dot = created.name.indexOf('.');
+            if (dot > 0) {
+                return {
+                    kind: facts.kind,
+                    schema: created.schema,
+                    name: created.name.slice(dot + 1),
+                    table: created.name.slice(0, dot)
+                };
+            }
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        }
+        case 'index': {
+            // IndexStmt records the index name in creates and the indexed relation
+            // in references (same-schema RangeVar).
+            const rel = facts.references.find(r => r.schema === created.schema) ?? facts.references[0];
+            return {
+                kind: 'index',
+                schema: created.schema,
+                name: created.name,
+                table: rel?.name
+            };
+        }
+        case 'fk_constraint':
+        case 'constraint':
+        case 'rls_enable':
+            // ALTER TABLE statements target their table.
+            return { kind: 'constraint', schema: created.schema, name: created.name, table: created.name };
+        case 'seed_dml':
+            return { kind: 'seed_dml', schema: created.schema, name: created.name, table: created.name };
+        case 'table':
+            // AlterTableStmt facts also classify as `table`-targeting; the created
+            // name is the table either way.
+            return { kind: 'table', schema: created.schema, name: created.name };
+        case 'view':
+        case 'function':
+        case 'type':
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        default:
+            if (facts.nodeTag === 'CreateSeqStmt') {
+                return { kind: 'sequence', schema: created.schema, name: created.name };
+            }
+            return { kind: 'other', schema: created.schema, name: created.name };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.9.0",
+  "version": "18.10.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": "ffe07838bbc332b12062679f4f0af6b952380cb1"
+  "gitHead": "ce8ea3fadd2549dfbe699c05c38c8a85090efc8c"
 }