node-type-registry 0.5.1 → 0.6.0

package/codegen/generate-types.d.ts

@@ -14,6 +14,6 @@
  * when building blueprint JSON.  The API itself accepts plain JSONB.
  *
  * Usage:
- *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>] [--meta <path>]
  */
 export {};

package/codegen/generate-types.js

@@ -15,7 +15,7 @@
  * when building blueprint JSON.  The API itself accepts plain JSONB.
  *
  * Usage:
- *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>] [--meta <path>]
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -165,9 +165,79 @@ function generateParamsInterfaces(nodeTypes) {
     return results;
 }
 // ---------------------------------------------------------------------------
-// Static structural types (BlueprintField, BlueprintPolicy, etc.)
+// Introspection-driven structural type derivation
 // ---------------------------------------------------------------------------
-function buildBlueprintField() {
+/** Map PostgreSQL type names to TypeScript type annotations. */
+function pgTypeToTSType(pgType, isArray) {
+    let base;
+    switch (pgType) {
+        case 'bool':
+        case 'boolean':
+            base = t.tsBooleanKeyword();
+            break;
+        case 'int2':
+        case 'int4':
+        case 'int8':
+        case 'integer':
+        case 'smallint':
+        case 'bigint':
+        case 'float4':
+        case 'float8':
+        case 'float':
+        case 'double precision':
+        case 'numeric':
+        case 'real':
+            base = t.tsNumberKeyword();
+            break;
+        case 'jsonb':
+        case 'json':
+            base = recordType(t.tsStringKeyword(), t.tsUnknownKeyword());
+            break;
+        default:
+            base = t.tsStringKeyword();
+            break;
+    }
+    return isArray ? t.tsArrayType(base) : base;
+}
+/**
+ * Derive a TS interface from an introspection table's columns.
+ *
+ * Fully procedural — uses field metadata to determine:
+ *   - Which columns to skip (isPrimaryKey || isForeignKey)
+ *   - Required vs optional (isNotNull && !hasDefault)
+ *   - JSDoc from PG column comments (description)
+ *
+ * Special-case overrides (e.g. typed discriminants) can be passed via
+ * `typeOverrides` for columns that need a non-default TS type.
+ */
+function deriveInterfaceFromTable(table, interfaceName, description, typeOverrides) {
+    const members = [];
+    for (const field of table.fields) {
+        // Skip PK and FK columns — these are internal to the DB schema
+        if (field.isPrimaryKey || field.isForeignKey)
+            continue;
+        const tsType = typeOverrides?.[field.name] ?? pgTypeToTSType(field.type.pgType, field.type.isArray);
+        const doc = field.description ?? `${table.schemaName}.${table.name}.${field.name} (${field.type.pgType})`;
+        const isRequired = field.isNotNull && !field.hasDefault;
+        const prop = isRequired
+            ? requiredProp(field.name, tsType)
+            : optionalProp(field.name, tsType);
+        members.push(addJSDoc(prop, doc));
+    }
+    return addJSDoc(exportInterface(interfaceName, members), description);
+}
+// ---------------------------------------------------------------------------
+// Structural types — introspection-driven or static fallback
+// ---------------------------------------------------------------------------
+function findTable(tables, schemaName, tableName) {
+    return tables.find((tbl) => tbl.schemaName === schemaName && tbl.name === tableName);
+}
+function buildBlueprintField(meta) {
+    const table = meta && findTable(meta, 'metaschema_public', 'field');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintField', 'A custom field (column) to add to a blueprint table. Derived from _meta.');
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintField', [
         addJSDoc(requiredProp('name', t.tsStringKeyword()), 'The column name.'),
         addJSDoc(requiredProp('type', t.tsStringKeyword()), 'The PostgreSQL type (e.g., "text", "integer", "boolean", "uuid").'),
@@ -176,12 +246,22 @@ function buildBlueprintField() {
         addJSDoc(optionalProp('description', t.tsStringKeyword()), 'Comment/description for this field.'),
     ]), 'A custom field (column) to add to a blueprint table.');
 }
-function buildBlueprintPolicy(authzNodes) {
+function buildBlueprintPolicy(authzNodes, meta) {
     const policyTypeAnnotation = authzNodes.length > 0
         ? strUnion(authzNodes.map((nt) => nt.name))
         : t.tsStringKeyword();
+    const table = meta && findTable(meta, 'metaschema_public', 'policy');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintPolicy', 'An RLS policy entry for a blueprint table. Derived from _meta.', {
+            // policy_type gets a typed union of known Authz* node names
+            policy_type: policyTypeAnnotation,
+            // data is untyped JSONB — use Record<string, unknown>
+            data: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+        });
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintPolicy', [
-        addJSDoc(requiredProp('$type', policyTypeAnnotation), 'Authz* policy type name (e.g., "AuthzDirectOwner", "AuthzAllowAll").'),
+        addJSDoc(requiredProp('policy_type', policyTypeAnnotation), 'Authz* policy type name (e.g., "AuthzDirectOwner", "AuthzAllowAll").'),
         addJSDoc(optionalProp('policy_role', t.tsStringKeyword()), 'Role for this policy. Defaults to "authenticated".'),
         addJSDoc(optionalProp('permissive', t.tsBooleanKeyword()), 'Whether this policy is permissive (true) or restrictive (false).'),
         addJSDoc(optionalProp('policy_name', t.tsStringKeyword()), 'Optional custom name for this policy.'),
@@ -203,11 +283,21 @@ function buildBlueprintFullTextSearch() {
         addJSDoc(requiredProp('sources', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintFtsSource')))), 'Source fields that feed into this tsvector.'),
     ]), 'A full-text search configuration for a blueprint table.');
 }
-function buildBlueprintIndex() {
+function buildBlueprintIndex(meta) {
+    const table = meta && findTable(meta, 'metaschema_public', 'index');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintIndex', 'An index definition within a blueprint. Derived from _meta.', {
+            // JSONB columns get Record<string, unknown> instead of the default
+            index_params: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+            where_clause: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+            options: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+        });
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintIndex', [
         addJSDoc(requiredProp('table_ref', t.tsStringKeyword()), 'Reference key of the table this index belongs to.'),
-        addJSDoc(optionalProp('column', t.tsStringKeyword()), 'Single column name for the index. Mutually exclusive with "columns".'),
-        addJSDoc(optionalProp('columns', t.tsArrayType(t.tsStringKeyword())), 'Array of column names for a multi-column index. Mutually exclusive with "column".'),
+        addJSDoc(optionalProp('column', t.tsStringKeyword()), 'Single column name for the index.'),
+        addJSDoc(optionalProp('columns', t.tsArrayType(t.tsStringKeyword())), 'Array of column names for a multi-column index.'),
         addJSDoc(requiredProp('access_method', t.tsStringKeyword()), 'Index access method (e.g., "BTREE", "GIN", "GIST", "HNSW", "BM25").'),
         addJSDoc(optionalProp('is_unique', t.tsBooleanKeyword()), 'Whether this is a unique index.'),
         addJSDoc(optionalProp('name', t.tsStringKeyword()), 'Optional custom name for the index.'),
@@ -300,7 +390,7 @@ function sectionComment(title) {
 // ---------------------------------------------------------------------------
 // Main generator
 // ---------------------------------------------------------------------------
-function buildProgram() {
+function buildProgram(meta) {
     const statements = [];
     // Group node types by category
     const categories = new Map();
@@ -321,13 +411,16 @@ function buildProgram() {
         statements.push(sectionComment(`${cat.charAt(0).toUpperCase() + cat.slice(1)} node type parameters`));
         statements.push(...generateParamsInterfaces(nts));
     }
-    // -- Static structural types --
-    statements.push(sectionComment('Static structural types'));
-    statements.push(buildBlueprintField());
-    statements.push(buildBlueprintPolicy(authzNodes));
+    // -- Structural types (_meta-driven when available, static fallback otherwise) --
+    const metaSource = meta
+        ? 'Derived from _meta'
+        : 'Static fallback (no _meta provided)';
+    statements.push(sectionComment(`Structural types — ${metaSource}`));
+    statements.push(buildBlueprintField(meta));
+    statements.push(buildBlueprintPolicy(authzNodes, meta));
     statements.push(buildBlueprintFtsSource());
     statements.push(buildBlueprintFullTextSearch());
-    statements.push(buildBlueprintIndex());
+    statements.push(buildBlueprintIndex(meta));
     // -- Node types discriminated union --
     statements.push(sectionComment('Node types -- discriminated union for nodes[] entries'));
     statements.push(...buildNodeTypes(dataNodes));
@@ -362,7 +455,26 @@ function main() {
     const args = process.argv.slice(2);
     const outdirIdx = args.indexOf('--outdir');
     const outdir = outdirIdx !== -1 ? args[outdirIdx + 1] : (0, path_1.join)(__dirname, '..');
-    const content = buildProgram();
+    const metaIdx = args.indexOf('--meta');
+    let meta;
+    if (metaIdx !== -1 && args[metaIdx + 1]) {
+        const metaPath = args[metaIdx + 1];
+        console.log(`Reading _meta from ${metaPath}`);
+        const raw = (0, fs_1.readFileSync)(metaPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Accept both { tables: [...] } (GQL query result) and raw [...] (array)
+        meta = (Array.isArray(parsed) ? parsed : parsed?.tables ?? parsed?.data?._meta?.tables);
+        if (meta) {
+            console.log(`Loaded ${meta.length} tables from _meta`);
+        }
+        else {
+            console.log('Could not find tables in _meta JSON; using static fallback types');
+        }
+    }
+    else {
+        console.log('No --meta flag; using static fallback types');
+    }
+    const content = buildProgram(meta);
     const filename = 'blueprint-types.generated.ts';
     const filepath = (0, path_1.join)(outdir, filename);
     if (!(0, fs_1.existsSync)(outdir))

package/esm/codegen/generate-types.d.ts

@@ -14,6 +14,6 @@
  * when building blueprint JSON.  The API itself accepts plain JSONB.
  *
  * Usage:
- *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>] [--meta <path>]
  */
 export {};

package/esm/codegen/generate-types.js

@@ -14,12 +14,12 @@
  * when building blueprint JSON.  The API itself accepts plain JSONB.
  *
  * Usage:
- *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>] [--meta <path>]
  */
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const generate = require('@babel/generator').default ?? require('@babel/generator');
 import * as t from '@babel/types';
-import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { generateTypeScriptTypes } from 'schema-typescript';
 import { allNodeTypes } from '../index';
@@ -130,9 +130,79 @@ function generateParamsInterfaces(nodeTypes) {
     return results;
 }
 // ---------------------------------------------------------------------------
-// Static structural types (BlueprintField, BlueprintPolicy, etc.)
+// Introspection-driven structural type derivation
 // ---------------------------------------------------------------------------
-function buildBlueprintField() {
+/** Map PostgreSQL type names to TypeScript type annotations. */
+function pgTypeToTSType(pgType, isArray) {
+    let base;
+    switch (pgType) {
+        case 'bool':
+        case 'boolean':
+            base = t.tsBooleanKeyword();
+            break;
+        case 'int2':
+        case 'int4':
+        case 'int8':
+        case 'integer':
+        case 'smallint':
+        case 'bigint':
+        case 'float4':
+        case 'float8':
+        case 'float':
+        case 'double precision':
+        case 'numeric':
+        case 'real':
+            base = t.tsNumberKeyword();
+            break;
+        case 'jsonb':
+        case 'json':
+            base = recordType(t.tsStringKeyword(), t.tsUnknownKeyword());
+            break;
+        default:
+            base = t.tsStringKeyword();
+            break;
+    }
+    return isArray ? t.tsArrayType(base) : base;
+}
+/**
+ * Derive a TS interface from an introspection table's columns.
+ *
+ * Fully procedural — uses field metadata to determine:
+ *   - Which columns to skip (isPrimaryKey || isForeignKey)
+ *   - Required vs optional (isNotNull && !hasDefault)
+ *   - JSDoc from PG column comments (description)
+ *
+ * Special-case overrides (e.g. typed discriminants) can be passed via
+ * `typeOverrides` for columns that need a non-default TS type.
+ */
+function deriveInterfaceFromTable(table, interfaceName, description, typeOverrides) {
+    const members = [];
+    for (const field of table.fields) {
+        // Skip PK and FK columns — these are internal to the DB schema
+        if (field.isPrimaryKey || field.isForeignKey)
+            continue;
+        const tsType = typeOverrides?.[field.name] ?? pgTypeToTSType(field.type.pgType, field.type.isArray);
+        const doc = field.description ?? `${table.schemaName}.${table.name}.${field.name} (${field.type.pgType})`;
+        const isRequired = field.isNotNull && !field.hasDefault;
+        const prop = isRequired
+            ? requiredProp(field.name, tsType)
+            : optionalProp(field.name, tsType);
+        members.push(addJSDoc(prop, doc));
+    }
+    return addJSDoc(exportInterface(interfaceName, members), description);
+}
+// ---------------------------------------------------------------------------
+// Structural types — introspection-driven or static fallback
+// ---------------------------------------------------------------------------
+function findTable(tables, schemaName, tableName) {
+    return tables.find((tbl) => tbl.schemaName === schemaName && tbl.name === tableName);
+}
+function buildBlueprintField(meta) {
+    const table = meta && findTable(meta, 'metaschema_public', 'field');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintField', 'A custom field (column) to add to a blueprint table. Derived from _meta.');
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintField', [
         addJSDoc(requiredProp('name', t.tsStringKeyword()), 'The column name.'),
         addJSDoc(requiredProp('type', t.tsStringKeyword()), 'The PostgreSQL type (e.g., "text", "integer", "boolean", "uuid").'),
@@ -141,12 +211,22 @@ function buildBlueprintField() {
         addJSDoc(optionalProp('description', t.tsStringKeyword()), 'Comment/description for this field.'),
     ]), 'A custom field (column) to add to a blueprint table.');
 }
-function buildBlueprintPolicy(authzNodes) {
+function buildBlueprintPolicy(authzNodes, meta) {
     const policyTypeAnnotation = authzNodes.length > 0
         ? strUnion(authzNodes.map((nt) => nt.name))
         : t.tsStringKeyword();
+    const table = meta && findTable(meta, 'metaschema_public', 'policy');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintPolicy', 'An RLS policy entry for a blueprint table. Derived from _meta.', {
+            // policy_type gets a typed union of known Authz* node names
+            policy_type: policyTypeAnnotation,
+            // data is untyped JSONB — use Record<string, unknown>
+            data: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+        });
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintPolicy', [
-        addJSDoc(requiredProp('$type', policyTypeAnnotation), 'Authz* policy type name (e.g., "AuthzDirectOwner", "AuthzAllowAll").'),
+        addJSDoc(requiredProp('policy_type', policyTypeAnnotation), 'Authz* policy type name (e.g., "AuthzDirectOwner", "AuthzAllowAll").'),
         addJSDoc(optionalProp('policy_role', t.tsStringKeyword()), 'Role for this policy. Defaults to "authenticated".'),
         addJSDoc(optionalProp('permissive', t.tsBooleanKeyword()), 'Whether this policy is permissive (true) or restrictive (false).'),
         addJSDoc(optionalProp('policy_name', t.tsStringKeyword()), 'Optional custom name for this policy.'),
@@ -168,11 +248,21 @@ function buildBlueprintFullTextSearch() {
         addJSDoc(requiredProp('sources', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintFtsSource')))), 'Source fields that feed into this tsvector.'),
     ]), 'A full-text search configuration for a blueprint table.');
 }
-function buildBlueprintIndex() {
+function buildBlueprintIndex(meta) {
+    const table = meta && findTable(meta, 'metaschema_public', 'index');
+    if (table) {
+        return deriveInterfaceFromTable(table, 'BlueprintIndex', 'An index definition within a blueprint. Derived from _meta.', {
+            // JSONB columns get Record<string, unknown> instead of the default
+            index_params: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+            where_clause: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+            options: recordType(t.tsStringKeyword(), t.tsUnknownKeyword()),
+        });
+    }
+    // Static fallback
     return addJSDoc(exportInterface('BlueprintIndex', [
         addJSDoc(requiredProp('table_ref', t.tsStringKeyword()), 'Reference key of the table this index belongs to.'),
-        addJSDoc(optionalProp('column', t.tsStringKeyword()), 'Single column name for the index. Mutually exclusive with "columns".'),
-        addJSDoc(optionalProp('columns', t.tsArrayType(t.tsStringKeyword())), 'Array of column names for a multi-column index. Mutually exclusive with "column".'),
+        addJSDoc(optionalProp('column', t.tsStringKeyword()), 'Single column name for the index.'),
+        addJSDoc(optionalProp('columns', t.tsArrayType(t.tsStringKeyword())), 'Array of column names for a multi-column index.'),
         addJSDoc(requiredProp('access_method', t.tsStringKeyword()), 'Index access method (e.g., "BTREE", "GIN", "GIST", "HNSW", "BM25").'),
         addJSDoc(optionalProp('is_unique', t.tsBooleanKeyword()), 'Whether this is a unique index.'),
         addJSDoc(optionalProp('name', t.tsStringKeyword()), 'Optional custom name for the index.'),
@@ -265,7 +355,7 @@ function sectionComment(title) {
 // ---------------------------------------------------------------------------
 // Main generator
 // ---------------------------------------------------------------------------
-function buildProgram() {
+function buildProgram(meta) {
     const statements = [];
     // Group node types by category
     const categories = new Map();
@@ -286,13 +376,16 @@ function buildProgram() {
         statements.push(sectionComment(`${cat.charAt(0).toUpperCase() + cat.slice(1)} node type parameters`));
         statements.push(...generateParamsInterfaces(nts));
     }
-    // -- Static structural types --
-    statements.push(sectionComment('Static structural types'));
-    statements.push(buildBlueprintField());
-    statements.push(buildBlueprintPolicy(authzNodes));
+    // -- Structural types (_meta-driven when available, static fallback otherwise) --
+    const metaSource = meta
+        ? 'Derived from _meta'
+        : 'Static fallback (no _meta provided)';
+    statements.push(sectionComment(`Structural types — ${metaSource}`));
+    statements.push(buildBlueprintField(meta));
+    statements.push(buildBlueprintPolicy(authzNodes, meta));
     statements.push(buildBlueprintFtsSource());
     statements.push(buildBlueprintFullTextSearch());
-    statements.push(buildBlueprintIndex());
+    statements.push(buildBlueprintIndex(meta));
     // -- Node types discriminated union --
     statements.push(sectionComment('Node types -- discriminated union for nodes[] entries'));
     statements.push(...buildNodeTypes(dataNodes));
@@ -327,7 +420,26 @@ function main() {
     const args = process.argv.slice(2);
     const outdirIdx = args.indexOf('--outdir');
     const outdir = outdirIdx !== -1 ? args[outdirIdx + 1] : join(__dirname, '..');
-    const content = buildProgram();
+    const metaIdx = args.indexOf('--meta');
+    let meta;
+    if (metaIdx !== -1 && args[metaIdx + 1]) {
+        const metaPath = args[metaIdx + 1];
+        console.log(`Reading _meta from ${metaPath}`);
+        const raw = readFileSync(metaPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Accept both { tables: [...] } (GQL query result) and raw [...] (array)
+        meta = (Array.isArray(parsed) ? parsed : parsed?.tables ?? parsed?.data?._meta?.tables);
+        if (meta) {
+            console.log(`Loaded ${meta.length} tables from _meta`);
+        }
+        else {
+            console.log('Could not find tables in _meta JSON; using static fallback types');
+        }
+    }
+    else {
+        console.log('No --meta flag; using static fallback types');
+    }
+    const content = buildProgram(meta);
     const filename = 'blueprint-types.generated.ts';
     const filepath = join(outdir, filename);
     if (!existsSync(outdir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-type-registry",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Node type definitions for the Constructive blueprint system. Single source of truth for all Authz*, Data*, Relation*, and View* node types.",
   "author": "Constructive <developers@constructive.io>",
   "main": "index.js",
@@ -34,12 +34,12 @@
     "@babel/generator": "^7.29.0",
     "@babel/types": "^7.29.0",
     "@pgsql/types": "^17.6.2",
-    "@pgsql/utils": "^17.8.14",
-    "pgsql-deparser": "^17.18.1",
-    "schema-typescript": "^0.14.2"
+    "@pgsql/utils": "^17.8.15",
+    "pgsql-deparser": "^17.18.2",
+    "schema-typescript": "^0.14.3"
   },
   "devDependencies": {
-    "makage": "^0.1.10"
+    "makage": "^0.3.0"
   },
   "keywords": [
     "constructive",
@@ -48,5 +48,5 @@
     "registry",
     "graphile"
   ],
-  "gitHead": "93deca687ce109bf90d2a0a73ea6b05b22724160"
+  "gitHead": "baae875effd00af36577612c861d0f6f9a1a792a"
 }