firebase-contract 0.1.0-rc.0

package/dist/lib/_internal/generators/typescript/typescript-split-generator.js

@@ -0,0 +1,175 @@
+import { findEnum, findModel } from '../../ir/ir.js';
+import { headerBlocks } from '../support/header.js';
+import { constantCase, singleQuote } from '../support/naming.js';
+import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
+import { collectDeps, kebabCase, splitGroups, tableNameOf } from '../support/split.js';
+const SCALAR_TS = {
+    string: 'string',
+    int: 'number',
+    int64: 'number',
+    float: 'number',
+    boolean: 'boolean',
+    timestamp: 'string',
+    date: 'string',
+    json: 'Json',
+    id: 'string',
+};
+const JSON_TYPE = [
+    'export type Json =',
+    '  | string',
+    '  | number',
+    '  | boolean',
+    '  | null',
+    '  | Json[]',
+    '  | { [key: string]: Json }',
+].join('\n');
+const renderRef = (ref) => {
+    switch (ref.kind) {
+        case 'scalar':
+            return SCALAR_TS[ref.name];
+        case 'enum':
+        case 'model':
+            return ref.name;
+        default:
+            return 'unknown';
+    }
+};
+const docLines = (description, indent) => {
+    if (!description)
+        return [];
+    const lines = description.split('\n');
+    if (lines.length === 1)
+        return [`${indent}/** ${lines[0]} */`];
+    return [`${indent}/**`, ...lines.map(line => `${indent} * ${line}`.trimEnd()), `${indent} */`];
+};
+const renderField = (field, ir) => {
+    const optional = field.optional ? '?' : '';
+    const doc = docLines(field.description, '  ');
+    let entry;
+    if (field.literal !== undefined) {
+        const type = field.list ? `${singleQuote(field.literal)}[]` : singleQuote(field.literal);
+        entry = `  ${field.name}${optional}: ${type}`;
+    }
+    else if (isRelation(field)) {
+        const base = SCALAR_TS[relationFkType(ir, field)];
+        entry = `  ${relationFkName(field)}${optional}: ${field.list ? `${base}[]` : base}`;
+    }
+    else {
+        const base = renderRef(field.type);
+        const type = field.list ? `${base}[]` : base;
+        const nullable = field.nullable ? ' | null' : '';
+        entry = `  ${field.name}${optional}: ${type}${nullable}`;
+    }
+    return [...doc, entry].join('\n');
+};
+const renderEnumConst = (irEnum) => {
+    const doc = docLines(irEnum.description, '');
+    const constName = constantCase(irEnum.name);
+    const entries = irEnum.values
+        .map(value => `  ${irEnum.valueKeys?.[value] ?? constantCase(value)}: ${singleQuote(value)},`)
+        .join('\n');
+    return [
+        ...doc,
+        `export const ${constName} = Object.freeze({`,
+        entries,
+        `} as const)`,
+        `export type ${irEnum.name}Key = keyof typeof ${constName}`,
+        `export type ${irEnum.name} = (typeof ${constName})[${irEnum.name}Key]`,
+    ].join('\n');
+};
+const renderModel = (model, ir) => {
+    const doc = docLines(model.description, '');
+    const fields = model.fields.map(field => renderField(field, ir)).join('\n');
+    return [...doc, `export interface ${model.name} {`, fields, '}'].join('\n');
+};
+const usesJson = (models) => models.some(model => model.fields.some(field => field.type.kind === 'scalar' && field.type.name === 'json'));
+/**
+ * Split variant of the TypeScript generator: one file per table at
+ * `types/<table-name>.ts` (kebab-case), with enums and embedded value objects
+ * co-located in the file of the first table that references them. Shared
+ * leftovers (and the `Json` type) live in `types/_shared.ts`, and `types.ts`
+ * is a barrel re-exporting every file.
+ */
+export const createTypeScriptSplitGenerator = () => ({
+    name: 'typescript-split',
+    description: 'TypeScript interfaces, one file per table (types/<table>.ts + types.ts barrel)',
+    generate(ir, context) {
+        const groups = splitGroups(ir);
+        const files = [];
+        const fileOf = new Map(); // symbol -> module basename (no ext)
+        const sharedNeeded = usesJson(ir.models) || groups.leftoverEnums.length > 0 || groups.leftoverModels.length > 0;
+        if (usesJson(ir.models))
+            fileOf.set('Json', '_shared');
+        for (const name of groups.leftoverEnums)
+            fileOf.set(name, '_shared');
+        for (const name of groups.leftoverModels)
+            fileOf.set(name, '_shared');
+        for (const table of groups.tables) {
+            const moduleName = kebabCase(tableNameOf(table));
+            fileOf.set(table.name, moduleName);
+            for (const [name, home] of groups.enumHome)
+                if (home === table.name)
+                    fileOf.set(name, moduleName);
+            for (const [name, home] of groups.modelHome)
+                if (home === table.name)
+                    fileOf.set(name, moduleName);
+        }
+        const emit = (moduleName, enums, models, includeJson) => {
+            const blocks = [...headerBlocks(context)];
+            // Imports for symbols declared in sibling files.
+            const external = new Map();
+            const need = (symbol) => {
+                const home = fileOf.get(symbol);
+                if (home && home !== moduleName) {
+                    const set = external.get(home) ?? new Set();
+                    set.add(symbol);
+                    external.set(home, set);
+                }
+            };
+            for (const model of models) {
+                for (const field of model.fields) {
+                    if (field.type.kind === 'scalar' && field.type.name === 'json')
+                        need('Json');
+                    // Literal-pinned and relation fields render without referencing the type.
+                    if (field.literal !== undefined || isRelation(field))
+                        continue;
+                    if (field.type.kind === 'enum' || field.type.kind === 'model')
+                        need(field.type.name);
+                }
+            }
+            const imports = [...external.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([home, symbols]) => `import type { ${[...symbols].sort().join(', ')} } from './${home}'`);
+            if (imports.length > 0)
+                blocks.push(imports.join('\n'));
+            if (includeJson)
+                blocks.push(JSON_TYPE);
+            for (const irEnum of enums)
+                blocks.push(renderEnumConst(irEnum));
+            for (const model of models)
+                blocks.push(renderModel(model, ir));
+            files.push({ path: `types/${moduleName}.ts`, content: `${blocks.join('\n\n')}\n` });
+        };
+        if (sharedNeeded) {
+            const enums = groups.leftoverEnums.map(name => findEnum(ir, name)).filter((e) => Boolean(e));
+            const models = groups.leftoverModels.map(name => findModel(ir, name)).filter((m) => Boolean(m));
+            emit('_shared', enums, models, usesJson(ir.models));
+        }
+        for (const table of groups.tables) {
+            const moduleName = kebabCase(tableNameOf(table));
+            const deps = collectDeps(ir, [table]);
+            const enums = deps.enums
+                .filter(name => groups.enumHome.get(name) === table.name)
+                .map(name => findEnum(ir, name))
+                .filter((e) => Boolean(e));
+            const models = deps.models
+                .filter(name => groups.modelHome.get(name) === table.name)
+                .map(name => findModel(ir, name))
+                .filter((m) => Boolean(m));
+            emit(moduleName, enums, [...models, table], false);
+        }
+        const exports = files.map(file => `export * from './${file.path.replace(/^types\//, 'types/').replace(/\.ts$/, '')}'`);
+        files.push({ path: 'types.ts', content: `${[...headerBlocks(context), exports.join('\n')].join('\n\n')}\n` });
+        return files;
+    },
+});

package/dist/lib/_internal/generators/union/union-generator.d.ts

@@ -0,0 +1,8 @@
+import { Generator } from '../generator.js';
+/**
+ * Generates Zod discriminated unions (and their TS union types) over model
+ * variants — e.g. a `z.discriminatedUnion('operationType', …)` of operation drafts.
+ * References the variant schemas/types from the zod and typescript outputs.
+ */
+export declare const createUnionGenerator: () => Generator;
+//# sourceMappingURL=union-generator.d.ts.map

package/dist/lib/_internal/generators/union/union-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"union-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/union/union-generator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAe5E;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAO,SAqBtC,CAAA"}

package/dist/lib/_internal/generators/union/union-generator.js

@@ -0,0 +1,37 @@
+import { singleQuote } from '../support/naming.js';
+import { headerBlocks } from '../support/header.js';
+const schemaName = (name) => `${name}Schema`;
+const renderUnion = (union) => {
+    const variantSchemas = union.variants.map(schemaName).join(', ');
+    const variantTypes = union.variants.join(' | ') || 'never';
+    const doc = union.description ? `/** ${union.description} */\n` : '';
+    return [
+        `${doc}export const ${schemaName(union.name)} = z.discriminatedUnion(${singleQuote(union.discriminant)}, [${variantSchemas}])`,
+        `export type ${union.name} = ${variantTypes}`,
+    ].join('\n');
+};
+/**
+ * Generates Zod discriminated unions (and their TS union types) over model
+ * variants — e.g. a `z.discriminatedUnion('operationType', …)` of operation drafts.
+ * References the variant schemas/types from the zod and typescript outputs.
+ */
+export const createUnionGenerator = () => ({
+    name: 'unions',
+    description: 'Zod discriminated unions + TS union types',
+    generate(ir, context) {
+        if (ir.unions.length === 0) {
+            return [];
+        }
+        const variantNames = [...new Set(ir.unions.flatMap(union => union.variants))].sort();
+        const blocks = [...headerBlocks(context), "import { z } from 'zod'"];
+        if (variantNames.length > 0) {
+            // One import block — a blank line between relative imports trips import/order.
+            blocks.push(`import { ${variantNames.map(schemaName).join(', ')} } from './schemas.js'\n` +
+                `import type { ${variantNames.join(', ')} } from './types.js'`);
+        }
+        for (const union of ir.unions) {
+            blocks.push(renderUnion(union));
+        }
+        return [{ path: 'unions.ts', content: `${blocks.join('\n\n')}\n` }];
+    },
+});

package/dist/lib/_internal/generators/zod/zod-generator.d.ts

@@ -0,0 +1,7 @@
+import { Generator } from '../generator.js';
+/**
+ * Generates Zod schemas and the types inferred from them. Model references use
+ * `z.lazy` so the output is order- and cycle-independent.
+ */
+export declare const createZodGenerator: () => Generator;
+//# sourceMappingURL=zod-generator.d.ts.map

package/dist/lib/_internal/generators/zod/zod-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/zod/zod-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAoD5E;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,SAwBpC,CAAA"}

package/dist/lib/_internal/generators/zod/zod-generator.js

@@ -0,0 +1,68 @@
+import { headerBlocks } from '../support/header.js';
+import { singleQuote } from '../support/naming.js';
+import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
+import { zodConstraints } from '../support/constraints.js';
+const SCALAR_ZOD = {
+    string: 'z.string()',
+    int: 'z.number().int()',
+    int64: 'z.number().int()',
+    float: 'z.number()',
+    boolean: 'z.boolean()',
+    timestamp: 'z.string().datetime()',
+    date: 'z.string()',
+    json: 'z.unknown()',
+    id: 'z.string()',
+};
+const schemaName = (name) => `${name}Schema`;
+const renderRef = (ref) => {
+    switch (ref.kind) {
+        case 'scalar':
+            return SCALAR_ZOD[ref.name];
+        case 'enum':
+            // Enums are declared before models, so a direct reference is safe.
+            return schemaName(ref.name);
+        case 'model':
+            // Model references are wrapped in z.lazy so declaration order and cycles
+            // never matter.
+            return `z.lazy(() => ${schemaName(ref.name)})`;
+        default:
+            return 'z.unknown()';
+    }
+};
+const renderFieldSchema = (field, ir) => {
+    const isRel = isRelation(field);
+    const name = isRel ? relationFkName(field) : field.name;
+    const base = field.literal !== undefined
+        ? `z.literal(${singleQuote(field.literal)})`
+        : isRel
+            ? SCALAR_ZOD[relationFkType(ir, field)]
+            : renderRef(field.type);
+    const cons = zodConstraints(field);
+    let schema = field.list ? `z.array(${base})${cons}` : `${base}${cons}`;
+    if (field.optional) {
+        schema = `${schema}.optional()`;
+    }
+    return `  ${name}: ${schema},`;
+};
+/**
+ * Generates Zod schemas and the types inferred from them. Model references use
+ * `z.lazy` so the output is order- and cycle-independent.
+ */
+export const createZodGenerator = () => ({
+    name: 'zod',
+    description: 'Zod validation schemas',
+    generate(ir, context) {
+        const blocks = [...headerBlocks(context), "import { z } from 'zod'"];
+        for (const irEnum of ir.enums) {
+            const values = irEnum.values.map(singleQuote).join(', ');
+            blocks.push(`export const ${schemaName(irEnum.name)} = z.enum([${values}])\n` +
+                `export type ${irEnum.name} = z.infer<typeof ${schemaName(irEnum.name)}>`);
+        }
+        for (const model of ir.models) {
+            const fields = model.fields.map(field => renderFieldSchema(field, ir)).join('\n');
+            blocks.push(`export const ${schemaName(model.name)} = z.object({\n${fields}\n})\n` +
+                `export type ${model.name} = z.infer<typeof ${schemaName(model.name)}>`);
+        }
+        return [{ path: 'schemas.ts', content: `${blocks.join('\n\n')}\n` }];
+    },
+});

package/dist/lib/_internal/generators/zod/zod-split-generator.d.ts

@@ -0,0 +1,9 @@
+import { Generator } from '../generator.js';
+/**
+ * Split variant of the Zod generator: one file per table at
+ * `schemas/<table-name>.ts` (kebab-case) with enums and embedded value objects
+ * co-located at their first referencing table, leftovers in
+ * `schemas/_shared.ts`, and a `schemas.ts` barrel.
+ */
+export declare const createZodSplitGenerator: () => Generator;
+//# sourceMappingURL=zod-split-generator.d.ts.map

package/dist/lib/_internal/generators/zod/zod-split-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-split-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/zod/zod-split-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAkE5E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAO,SAkEzC,CAAA"}

package/dist/lib/_internal/generators/zod/zod-split-generator.js

@@ -0,0 +1,136 @@
+import { findEnum, findModel } from '../../ir/ir.js';
+import { zodConstraints } from '../support/constraints.js';
+import { headerBlocks } from '../support/header.js';
+import { singleQuote } from '../support/naming.js';
+import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
+import { collectDeps, kebabCase, splitGroups, tableNameOf } from '../support/split.js';
+const SCALAR_ZOD = {
+    string: 'z.string()',
+    int: 'z.number().int()',
+    int64: 'z.number().int()',
+    float: 'z.number()',
+    boolean: 'z.boolean()',
+    timestamp: 'z.string().datetime()',
+    date: 'z.string()',
+    json: 'z.unknown()',
+    id: 'z.string()',
+};
+const schemaName = (name) => `${name}Schema`;
+const renderRef = (ref) => {
+    switch (ref.kind) {
+        case 'scalar':
+            return SCALAR_ZOD[ref.name];
+        case 'enum':
+            return schemaName(ref.name);
+        case 'model':
+            // Wrapped in z.lazy so declaration order and (cross-file) cycles never matter.
+            return `z.lazy(() => ${schemaName(ref.name)})`;
+        default:
+            return 'z.unknown()';
+    }
+};
+const renderFieldSchema = (field, ir) => {
+    const isRel = isRelation(field);
+    const name = isRel ? relationFkName(field) : field.name;
+    const base = field.literal !== undefined
+        ? `z.literal(${singleQuote(field.literal)})`
+        : isRel
+            ? SCALAR_ZOD[relationFkType(ir, field)]
+            : renderRef(field.type);
+    const cons = zodConstraints(field);
+    let schema = field.list ? `z.array(${base})${cons}` : `${base}${cons}`;
+    if (field.nullable)
+        schema = `${schema}.nullable()`;
+    if (field.optional)
+        schema = `${schema}.optional()`;
+    return `  ${name}: ${schema},`;
+};
+const renderEnum = (irEnum) => {
+    const values = irEnum.values.map(singleQuote).join(', ');
+    return (`export const ${schemaName(irEnum.name)} = z.enum([${values}])\n` +
+        `export type ${irEnum.name} = z.infer<typeof ${schemaName(irEnum.name)}>`);
+};
+const renderModel = (model, ir) => {
+    const fields = model.fields.map(field => renderFieldSchema(field, ir)).join('\n');
+    return (`export const ${schemaName(model.name)} = z.object({\n${fields}\n})\n` +
+        `export type ${model.name} = z.infer<typeof ${schemaName(model.name)}>`);
+};
+/**
+ * Split variant of the Zod generator: one file per table at
+ * `schemas/<table-name>.ts` (kebab-case) with enums and embedded value objects
+ * co-located at their first referencing table, leftovers in
+ * `schemas/_shared.ts`, and a `schemas.ts` barrel.
+ */
+export const createZodSplitGenerator = () => ({
+    name: 'zod-split',
+    description: 'Zod schemas, one file per table (schemas/<table>.ts + schemas.ts barrel)',
+    generate(ir, context) {
+        const groups = splitGroups(ir);
+        const files = [];
+        const fileOf = new Map();
+        for (const name of groups.leftoverEnums)
+            fileOf.set(name, '_shared');
+        for (const name of groups.leftoverModels)
+            fileOf.set(name, '_shared');
+        for (const table of groups.tables) {
+            const moduleName = kebabCase(tableNameOf(table));
+            fileOf.set(table.name, moduleName);
+            for (const [name, home] of groups.enumHome)
+                if (home === table.name)
+                    fileOf.set(name, moduleName);
+            for (const [name, home] of groups.modelHome)
+                if (home === table.name)
+                    fileOf.set(name, moduleName);
+        }
+        const emit = (moduleName, enums, models) => {
+            const blocks = [...headerBlocks(context), "import { z } from 'zod'"];
+            const external = new Map();
+            for (const model of models) {
+                for (const field of model.fields) {
+                    // Literal-pinned and relation fields render without referencing the schema.
+                    if (field.literal !== undefined || isRelation(field))
+                        continue;
+                    if (field.type.kind !== 'enum' && field.type.kind !== 'model')
+                        continue;
+                    const home = fileOf.get(field.type.name);
+                    if (home && home !== moduleName) {
+                        const set = external.get(home) ?? new Set();
+                        set.add(schemaName(field.type.name));
+                        external.set(home, set);
+                    }
+                }
+            }
+            const imports = [...external.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([home, symbols]) => `import { ${[...symbols].sort().join(', ')} } from './${home}'`);
+            if (imports.length > 0)
+                blocks.push(imports.join('\n'));
+            for (const irEnum of enums)
+                blocks.push(renderEnum(irEnum));
+            for (const model of models)
+                blocks.push(renderModel(model, ir));
+            files.push({ path: `schemas/${moduleName}.ts`, content: `${blocks.join('\n\n')}\n` });
+        };
+        if (groups.leftoverEnums.length > 0 || groups.leftoverModels.length > 0) {
+            const enums = groups.leftoverEnums.map(name => findEnum(ir, name)).filter((e) => Boolean(e));
+            const models = groups.leftoverModels.map(name => findModel(ir, name)).filter((m) => Boolean(m));
+            emit('_shared', enums, models);
+        }
+        for (const table of groups.tables) {
+            const moduleName = kebabCase(tableNameOf(table));
+            const deps = collectDeps(ir, [table]);
+            const enums = deps.enums
+                .filter(name => groups.enumHome.get(name) === table.name)
+                .map(name => findEnum(ir, name))
+                .filter((e) => Boolean(e));
+            const models = deps.models
+                .filter(name => groups.modelHome.get(name) === table.name)
+                .map(name => findModel(ir, name))
+                .filter((m) => Boolean(m));
+            emit(moduleName, enums, [...models, table]);
+        }
+        const exports = files.map(file => `export * from './${file.path.replace(/\.ts$/, '')}'`);
+        files.push({ path: 'schemas.ts', content: `${[...headerBlocks(context), exports.join('\n')].join('\n\n')}\n` });
+        return files;
+    },
+});

package/dist/lib/_internal/ir/build-ir.d.ts

@@ -0,0 +1,18 @@
+import { Diagnostic } from '../diagnostics.js';
+import { RawContract } from '../parser/raw-document.js';
+import { Ir } from './ir.js';
+export interface BuildIrResult {
+    ir: Ir;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Merge every resolved document into one normalized {@link Ir}.
+ *
+ * Type names on fields are resolved against the full set of enums and models
+ * gathered from all documents, so imports work transparently. Names defined in
+ * more than one place are reported as `DUPLICATE_DEFINITION` and the first
+ * definition wins. Unknown type names are left as `unresolved` refs for the
+ * validation step to flag.
+ */
+export declare const buildIr: (documents: RawContract[]) => BuildIrResult;
+//# sourceMappingURL=build-ir.d.ts.map

package/dist/lib/_internal/ir/build-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-ir.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/ir/build-ir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAS,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAGL,WAAW,EAIZ,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAGL,EAAE,EAgBH,MAAM,SAAS,CAAA;AAEhB,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAoLD;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,WAAW,EAAE,KAAG,aAqQlD,CAAA"}