node-type-registry 0.4.0 → 0.5.1

package/blueprint-types.generated.js

@@ -0,0 +1,57 @@
+"use strict";
+// GENERATED FILE — DO NOT EDIT
+//
+// Regenerate with:
+//   cd graphile/node-type-registry && pnpm generate:types
+//
+// These types match the JSONB shape expected by construct_blueprint().
+// All field names are snake_case to match the SQL convention.
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * ===========================================================================
+ * Data node type parameters
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Authz node type parameters
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Relation node type parameters
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * View node type parameters
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Static structural types
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Node types -- discriminated union for nodes[] entries
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Relation types
+ * ===========================================================================
+ */
+;
+/**
+ * ===========================================================================
+ * Blueprint table and definition
+ * ===========================================================================
+ */
+;

package/codegen/generate-types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generate TypeScript types for blueprint definitions from node type registry.
+ *
+ * Uses @babel/types AST nodes + schema-typescript for JSON Schema -> TS
+ * conversion.  Produces a `blueprint-types.generated.ts` file with:
+ *
+ *   - Per-node-type parameter interfaces (via schema-typescript)
+ *   - BlueprintNode  -- discriminated union of all non-relation node types
+ *   - BlueprintRelation -- typed relation entries with $type, source_ref, target_ref
+ *   - BlueprintTable, BlueprintField, BlueprintPolicy, BlueprintIndex, etc.
+ *   - BlueprintDefinition -- the top-level type matching the JSONB shape
+ *
+ * These types are client-side only -- they provide autocomplete and type safety
+ * when building blueprint JSON.  The API itself accepts plain JSONB.
+ *
+ * Usage:
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ */
+export {};

package/codegen/generate-types.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Generate TypeScript types for blueprint definitions from node type registry.
+ *
+ * Uses @babel/types AST nodes + schema-typescript for JSON Schema -> TS
+ * conversion.  Produces a `blueprint-types.generated.ts` file with:
+ *
+ *   - Per-node-type parameter interfaces (via schema-typescript)
+ *   - BlueprintNode  -- discriminated union of all non-relation node types
+ *   - BlueprintRelation -- typed relation entries with $type, source_ref, target_ref
+ *   - BlueprintTable, BlueprintField, BlueprintPolicy, BlueprintIndex, etc.
+ *   - BlueprintDefinition -- the top-level type matching the JSONB shape
+ *
+ * These types are client-side only -- they provide autocomplete and type safety
+ * when building blueprint JSON.  The API itself accepts plain JSONB.
+ *
+ * Usage:
+ *   npx ts-node src/codegen/generate-types.ts [--outdir <dir>]
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const generate = require('@babel/generator').default ?? require('@babel/generator');
+const t = __importStar(require("@babel/types"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const schema_typescript_1 = require("schema-typescript");
+const index_1 = require("../index");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Attach a JSDoc-style leading comment to an AST node. */
+function addJSDoc(node, description) {
+    node.leadingComments = [
+        { type: 'CommentBlock', value: `* ${description} ` },
+    ];
+    return node;
+}
+/** Create an optional TSPropertySignature. */
+function optionalProp(name, typeAnnotation) {
+    const prop = t.tsPropertySignature(t.identifier(name), t.tsTypeAnnotation(typeAnnotation));
+    prop.optional = true;
+    return prop;
+}
+/** Create a required TSPropertySignature. */
+function requiredProp(name, typeAnnotation) {
+    return t.tsPropertySignature(t.identifier(name), t.tsTypeAnnotation(typeAnnotation));
+}
+/** Create an exported interface declaration. */
+function exportInterface(name, members) {
+    return t.exportNamedDeclaration(t.tsInterfaceDeclaration(t.identifier(name), null, [], t.tsInterfaceBody(members)));
+}
+/** Create an exported type alias. */
+function exportTypeAlias(name, type) {
+    return t.exportNamedDeclaration(t.tsTypeAliasDeclaration(t.identifier(name), null, type));
+}
+/** Create a string literal type. */
+function strLit(value) {
+    return t.tsLiteralType(t.stringLiteral(value));
+}
+/** Create a union of string literals. */
+function strUnion(values) {
+    if (values.length === 1)
+        return strLit(values[0]);
+    return t.tsUnionType(values.map(strLit));
+}
+/** Create Record<K, V> type reference. */
+function recordType(keyType, valueType) {
+    return t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([keyType, valueType]));
+}
+/** Create Partial<T> type reference. */
+function partialOf(inner) {
+    return t.tsTypeReference(t.identifier('Partial'), t.tsTypeParameterInstantiation([inner]));
+}
+// ---------------------------------------------------------------------------
+// Schema sanitizer — ensures array types have an items spec (schema-typescript
+// throws without one).  Numeric/boolean enum handling is fixed upstream as of
+// schema-typescript@0.14.2.
+// ---------------------------------------------------------------------------
+function ensureArrayItems(schema) {
+    const out = { ...schema };
+    // Ensure arrays have an items spec (schema-typescript throws without one)
+    if (out.type === 'array' && !out.items) {
+        out.items = { type: 'string' };
+    }
+    // Recurse into properties
+    if (out.properties && typeof out.properties === 'object') {
+        const props = {};
+        for (const [k, v] of Object.entries(out.properties)) {
+            props[k] = v && typeof v === 'object' ? ensureArrayItems(v) : v;
+        }
+        out.properties = props;
+    }
+    // Recurse into items
+    if (out.items && typeof out.items === 'object') {
+        out.items = ensureArrayItems(out.items);
+    }
+    // Recurse into composition keywords
+    for (const keyword of ['oneOf', 'anyOf', 'allOf']) {
+        if (Array.isArray(out[keyword])) {
+            out[keyword] = out[keyword].map((s) => s && typeof s === 'object' ? ensureArrayItems(s) : s);
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Generate per-node-type parameter interfaces via schema-typescript
+// ---------------------------------------------------------------------------
+function generateParamsInterfaces(nodeTypes) {
+    const results = [];
+    for (const nt of nodeTypes) {
+        const schema = nt.parameter_schema;
+        const typeName = `${nt.name}Params`;
+        const sanitized = ensureArrayItems({ ...schema, title: typeName });
+        const astNodes = (0, schema_typescript_1.generateTypeScriptTypes)(sanitized, {
+            includePropertyComments: true,
+            includeTypeComments: false,
+            strictTypeSafety: true,
+        });
+        if (astNodes.length > 0) {
+            // The last node is the main interface for the title
+            const mainNode = astNodes[astNodes.length - 1];
+            addJSDoc(mainNode, nt.description);
+            for (const node of astNodes) {
+                results.push(node);
+            }
+        }
+        else {
+            // Fallback: empty interface for node types with no properties
+            results.push(addJSDoc(exportInterface(typeName, []), nt.description));
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Static structural types (BlueprintField, BlueprintPolicy, etc.)
+// ---------------------------------------------------------------------------
+function buildBlueprintField() {
+    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").'),
+        addJSDoc(optionalProp('is_required', t.tsBooleanKeyword()), 'Whether the column has a NOT NULL constraint.'),
+        addJSDoc(optionalProp('default_value', t.tsStringKeyword()), 'SQL default value expression (e.g., "true", "now()").'),
+        addJSDoc(optionalProp('description', t.tsStringKeyword()), 'Comment/description for this field.'),
+    ]), 'A custom field (column) to add to a blueprint table.');
+}
+function buildBlueprintPolicy(authzNodes) {
+    const policyTypeAnnotation = authzNodes.length > 0
+        ? strUnion(authzNodes.map((nt) => nt.name))
+        : t.tsStringKeyword();
+    return addJSDoc(exportInterface('BlueprintPolicy', [
+        addJSDoc(requiredProp('$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.'),
+        addJSDoc(optionalProp('privileges', t.tsArrayType(t.tsStringKeyword())), 'Privileges this policy applies to.'),
+        addJSDoc(optionalProp('data', recordType(t.tsStringKeyword(), t.tsUnknownKeyword())), 'Policy-specific data (structure varies by policy type).'),
+    ]), 'An RLS policy entry for a blueprint table.');
+}
+function buildBlueprintFtsSource() {
+    return addJSDoc(exportInterface('BlueprintFtsSource', [
+        addJSDoc(requiredProp('field', t.tsStringKeyword()), 'Column name of the source field.'),
+        addJSDoc(requiredProp('weight', t.tsStringKeyword()), 'TSVector weight: "A", "B", "C", or "D".'),
+        addJSDoc(optionalProp('lang', t.tsStringKeyword()), 'Language for text search. Defaults to "english".'),
+    ]), 'A source field contributing to a full-text search tsvector column.');
+}
+function buildBlueprintFullTextSearch() {
+    return addJSDoc(exportInterface('BlueprintFullTextSearch', [
+        addJSDoc(requiredProp('table_ref', t.tsStringKeyword()), 'Reference key of the table this full-text search belongs to.'),
+        addJSDoc(requiredProp('field', t.tsStringKeyword()), 'Name of the tsvector field on the table.'),
+        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() {
+    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(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.'),
+        addJSDoc(optionalProp('op_classes', t.tsArrayType(t.tsStringKeyword())), 'Operator classes for the index columns.'),
+        addJSDoc(optionalProp('options', recordType(t.tsStringKeyword(), t.tsUnknownKeyword())), 'Additional index-specific options.'),
+    ]), 'An index definition within a blueprint.');
+}
+// ---------------------------------------------------------------------------
+// Node type discriminated unions
+// ---------------------------------------------------------------------------
+function buildNodeTypes(dataNodes) {
+    const results = [];
+    // BlueprintNodeShorthand -- union of string literals
+    results.push(addJSDoc(exportTypeAlias('BlueprintNodeShorthand', strUnion(dataNodes.map((nt) => nt.name))), 'String shorthand -- just the node type name.'));
+    // BlueprintNodeObject -- discriminated union of { $type, data } objects
+    const objectMembers = dataNodes.map((nt) => {
+        const hasParams = nt.parameter_schema.properties &&
+            Object.keys(nt.parameter_schema.properties).length > 0;
+        const dataType = hasParams
+            ? t.tsTypeReference(t.identifier(`${nt.name}Params`))
+            : recordType(t.tsStringKeyword(), t.tsNeverKeyword());
+        const dataProp = hasParams
+            ? requiredProp('data', dataType)
+            : optionalProp('data', dataType);
+        return t.tsTypeLiteral([requiredProp('$type', strLit(nt.name)), dataProp]);
+    });
+    results.push(addJSDoc(exportTypeAlias('BlueprintNodeObject', t.tsUnionType(objectMembers)), 'Object form -- { $type, data } with typed parameters.'));
+    // BlueprintNode -- shorthand | object
+    results.push(addJSDoc(exportTypeAlias('BlueprintNode', t.tsUnionType([
+        t.tsTypeReference(t.identifier('BlueprintNodeShorthand')),
+        t.tsTypeReference(t.identifier('BlueprintNodeObject')),
+    ])), 'A node entry in a blueprint table. Either a string shorthand or a typed object.'));
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Relation types
+// ---------------------------------------------------------------------------
+function buildRelationTypes(relationNodes) {
+    const relationMembers = relationNodes.map((nt) => {
+        const baseType = t.tsTypeLiteral([
+            requiredProp('$type', strLit(nt.name)),
+            requiredProp('source_ref', t.tsStringKeyword()),
+            requiredProp('target_ref', t.tsStringKeyword()),
+        ]);
+        return t.tsIntersectionType([
+            baseType,
+            partialOf(t.tsTypeReference(t.identifier(`${nt.name}Params`))),
+        ]);
+    });
+    return [
+        addJSDoc(exportTypeAlias('BlueprintRelation', t.tsUnionType(relationMembers)), 'A relation entry in a blueprint definition.'),
+    ];
+}
+// ---------------------------------------------------------------------------
+// BlueprintTable and BlueprintDefinition
+// ---------------------------------------------------------------------------
+function buildBlueprintTable() {
+    return addJSDoc(exportInterface('BlueprintTable', [
+        addJSDoc(requiredProp('ref', t.tsStringKeyword()), 'Local reference key for this table (used by relations, indexes, fts).'),
+        addJSDoc(requiredProp('table_name', t.tsStringKeyword()), 'The PostgreSQL table name to create.'),
+        addJSDoc(requiredProp('nodes', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintNode')))), "Array of node type entries that define the table's behavior."),
+        addJSDoc(optionalProp('fields', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintField')))), 'Custom fields (columns) to add to the table.'),
+        addJSDoc(optionalProp('policies', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintPolicy')))), 'RLS policies for this table.'),
+        addJSDoc(optionalProp('grant_roles', t.tsArrayType(t.tsStringKeyword())), 'Database roles to grant privileges to. Defaults to ["authenticated"].'),
+        addJSDoc(optionalProp('grants', t.tsArrayType(t.tsUnknownKeyword())), 'Privilege grants as [verb, column] tuples or objects.'),
+        addJSDoc(optionalProp('use_rls', t.tsBooleanKeyword()), 'Whether to enable RLS on this table. Defaults to true.'),
+    ]), 'A table definition within a blueprint.');
+}
+function buildBlueprintDefinition() {
+    return addJSDoc(exportInterface('BlueprintDefinition', [
+        addJSDoc(requiredProp('tables', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintTable')))), 'Tables to create.'),
+        addJSDoc(optionalProp('relations', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintRelation')))), 'Relations between tables.'),
+        addJSDoc(optionalProp('indexes', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintIndex')))), 'Indexes on table columns.'),
+        addJSDoc(optionalProp('full_text_searches', t.tsArrayType(t.tsTypeReference(t.identifier('BlueprintFullTextSearch')))), 'Full-text search configurations.'),
+    ]), 'The complete blueprint definition -- the JSONB shape accepted by construct_blueprint().');
+}
+// ---------------------------------------------------------------------------
+// Section comment helper
+// ---------------------------------------------------------------------------
+function sectionComment(title) {
+    const empty = t.emptyStatement();
+    empty.leadingComments = [
+        {
+            type: 'CommentBlock',
+            value: `*\n * ===========================================================================\n * ${title}\n * ===========================================================================\n `,
+        },
+    ];
+    return empty;
+}
+// ---------------------------------------------------------------------------
+// Main generator
+// ---------------------------------------------------------------------------
+function buildProgram() {
+    const statements = [];
+    // Group node types by category
+    const categories = new Map();
+    for (const nt of index_1.allNodeTypes) {
+        const list = categories.get(nt.category) ?? [];
+        list.push(nt);
+        categories.set(nt.category, list);
+    }
+    const dataNodes = index_1.allNodeTypes.filter((nt) => nt.category !== 'relation' && nt.category !== 'view');
+    const relationNodes = index_1.allNodeTypes.filter((nt) => nt.category === 'relation');
+    const authzNodes = index_1.allNodeTypes.filter((nt) => nt.category === 'authz');
+    // -- Parameter interfaces grouped by category --
+    const categoryOrder = ['data', 'authz', 'relation', 'view'];
+    for (const cat of categoryOrder) {
+        const nts = categories.get(cat);
+        if (!nts || nts.length === 0)
+            continue;
+        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));
+    statements.push(buildBlueprintFtsSource());
+    statements.push(buildBlueprintFullTextSearch());
+    statements.push(buildBlueprintIndex());
+    // -- Node types discriminated union --
+    statements.push(sectionComment('Node types -- discriminated union for nodes[] entries'));
+    statements.push(...buildNodeTypes(dataNodes));
+    // -- Relation types --
+    statements.push(sectionComment('Relation types'));
+    statements.push(...buildRelationTypes(relationNodes));
+    // -- Blueprint table and definition --
+    statements.push(sectionComment('Blueprint table and definition'));
+    statements.push(buildBlueprintTable());
+    statements.push(buildBlueprintDefinition());
+    // Build the full AST and render to code
+    const program = t.program(statements);
+    const file = t.file(program);
+    const header = [
+        '// GENERATED FILE \u2014 DO NOT EDIT',
+        '//',
+        '// Regenerate with:',
+        '//   cd graphile/node-type-registry && pnpm generate:types',
+        '//',
+        '// These types match the JSONB shape expected by construct_blueprint().',
+        '// All field names are snake_case to match the SQL convention.',
+        '',
+        '',
+    ].join('\n');
+    const output = generate(file, { comments: true });
+    return header + output.code + '\n';
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+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 filename = 'blueprint-types.generated.ts';
+    const filepath = (0, path_1.join)(outdir, filename);
+    if (!(0, fs_1.existsSync)(outdir))
+        (0, fs_1.mkdirSync)(outdir, { recursive: true });
+    (0, fs_1.writeFileSync)(filepath, content);
+    console.log(`Generated ${filepath} (${index_1.allNodeTypes.length} node types)`);
+}
+main();