firebase-contract 0.1.0-rc.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-split-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/firestore/firestore-split-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAwO5E;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,QAAO,SAqI/C,CAAA"}

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

@@ -0,0 +1,375 @@
+import { findEnum, findModel } from '../../ir/ir.js';
+import { zodConstraints } from '../support/constraints.js';
+import { headerBlocks } from '../support/header.js';
+import { camelCase, constantCase, pluralize, singleQuote } from '../support/naming.js';
+import { isRelation, relationFkName } from '../support/relations.js';
+import { collectDeps, kebabCase, tableNameOf } from '../support/split.js';
+// Projection-level scalars: timestamps become dates, ids/relations become
+// resolved (hashids-encoded) string ids.
+const SCALAR_FS = {
+    string: 'z.string()',
+    int: 'z.number()',
+    int64: 'z.number()',
+    float: 'z.number()',
+    boolean: 'z.boolean()',
+    timestamp: 'z.date()',
+    date: 'z.date()',
+    json: 'z.unknown()',
+    id: 'z.string()',
+};
+// Embedded value objects keep the stricter Zod chains (`.int()` etc.).
+const SCALAR_EMBEDDED = {
+    ...SCALAR_FS,
+    int: 'z.number().int()',
+    int64: 'z.number().int()',
+};
+const META_FILE = `import { z } from 'zod'
+
+/**
+ * Cloud Task 整合性管理用の operation 識別子メタ。
+ * 整合性回復 (reconciliation) 処理の最新世代を表す。
+ */
+export const _Meta_OperationSchema = z.object({
+  /** opId (operation id) */
+  id: z.string(),
+  /** 整合性回復処理の識別子 */
+  identifierId: z.string(),
+  /** unixtime (最終更新) */
+  updatedAt: z.number(),
+})
+export type _Meta_Operation = z.infer<typeof _Meta_OperationSchema>
+
+/**
+ * 全 Firestore document に付ける整合性管理メタ。
+ *
+ * - \`scope\`: app hosting 経由で set される unixtime
+ * - \`sys\`:   cloud functions / cloud task 経由で set される unixtime
+ * - \`op\`:    cloud task で set される operation メタ
+ */
+export const _Meta_Schema = z.object({
+  scope: z.number().nullable(),
+  sys: z.number().nullable(),
+  op: _Meta_OperationSchema.nullable(),
+})
+export type _Meta_ = z.infer<typeof _Meta_Schema>
+`;
+const lineComments = (description, indent) => description ? description.split('\n').map(line => `${indent}// ${line}`.trimEnd()) : [];
+const jsdoc = (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 fsEnumName = (irEnum) => irEnum.fsName ?? irEnum.name;
+const fsModelName = (ir, name) => findModel(ir, name)?.fsName ?? name;
+/**
+ * Frozen const object + Key/value types + Zod enum referencing the const —
+ * the hand-maintained representation this generator standardizes on.
+ */
+const renderFsEnum = (irEnum) => {
+    const name = fsEnumName(irEnum);
+    const constName = constantCase(name);
+    const keyOf = (value) => irEnum.valueKeys?.[value] ?? constantCase(value);
+    const entries = irEnum.values.map(value => `  ${keyOf(value)}: ${singleQuote(value)},`);
+    const schemaValues = irEnum.values.map(value => `  ${constName}.${keyOf(value)},`);
+    return [
+        ...lineComments(irEnum.fsDescription ?? irEnum.description, ''),
+        `export const ${constName} = Object.freeze({`,
+        ...entries,
+        `} as const)`,
+        `export type ${name}Key = keyof typeof ${constName}`,
+        `export type ${name} = (typeof ${constName})[${name}Key]`,
+        `export const ${name}Schema = z.enum([`,
+        ...schemaValues,
+        `])`,
+    ].join('\n');
+};
+/** Zod chain for one field of an embedded value object. */
+const embeddedFieldSchema = (ir, field) => {
+    let base;
+    if (field.type.kind === 'scalar')
+        base = SCALAR_EMBEDDED[field.type.name];
+    else if (field.type.kind === 'enum') {
+        const irEnum = findEnum(ir, field.type.name);
+        base = irEnum ? `${fsEnumName(irEnum)}Schema` : 'z.string()';
+    }
+    else if (field.type.kind === 'model')
+        base = `${fsModelName(ir, field.type.name)}Schema`;
+    else
+        base = 'z.unknown()';
+    let schema = field.list ? `z.array(${base})${zodConstraints(field)}` : `${base}${zodConstraints(field)}`;
+    if (field.default !== undefined)
+        schema = `${schema}.default(${JSON.stringify(field.default)})`;
+    if (field.nullable)
+        schema = `${schema}.nullable()`;
+    if (field.optional)
+        schema = `${schema}.optional()`;
+    return schema;
+};
+const renderEmbeddedModel = (ir, model) => {
+    const lines = [];
+    const desc = model.description ?? '';
+    const name = model.fsName ?? model.name;
+    lines.push(...(desc.includes('\n') ? jsdoc(desc, '') : lineComments(desc || undefined, '')));
+    lines.push(`export const ${name}Schema = z.object({`);
+    for (const field of model.fields) {
+        lines.push(...jsdoc(field.description, '  '));
+        lines.push(`  ${field.name}: ${embeddedFieldSchema(ir, field)},`);
+    }
+    lines.push('})');
+    lines.push(`export type ${name} = z.infer<typeof ${name}Schema>`);
+    return lines.join('\n');
+};
+// zod-split と同じ DC 側チェーン。FS 側と文字列一致するフィールドは
+// `.pick()` で DC スキーマから流用できる。
+const SCALAR_DC = {
+    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 dcFieldChain = (ir, field) => {
+    const base = isRelation(field)
+        ? SCALAR_DC[findModel(ir, field.type.kind === 'model' ? field.type.name : '')?.fields.find(f => f.isId)?.type?.name ?? 'string']
+        : field.type.kind === 'scalar'
+            ? SCALAR_DC[field.type.name]
+            : field.type.kind === 'enum'
+                ? `${field.type.name}Schema`
+                : 'z.unknown()';
+    let chain = field.list ? `z.array(${base})${zodConstraints(field)}` : `${base}${zodConstraints(field)}`;
+    if (field.nullable)
+        chain = `${chain}.nullable()`;
+    if (field.optional)
+        chain = `${chain}.optional()`;
+    return chain;
+};
+/** Zod chain for a base (picked) Data Connect field in the projection. */
+const baseFieldSchema = (ir, field) => {
+    const name = isRelation(field) ? relationFkName(field) : field.name;
+    let base;
+    if (isRelation(field))
+        base = 'z.string()'; // resolved, encoded foreign-key id
+    else if (field.type.kind === 'enum') {
+        const irEnum = findEnum(ir, field.type.name);
+        base = irEnum ? `${fsEnumName(irEnum)}Schema` : 'z.string()';
+    }
+    else if (field.type.kind === 'scalar')
+        base = SCALAR_FS[field.type.name];
+    else if (field.type.kind === 'model')
+        base = `${fsModelName(ir, field.type.name)}Schema`;
+    else
+        base = 'z.unknown()';
+    let schema = field.list ? `z.array(${base})` : base;
+    if (field.optional)
+        schema = `${schema}.nullable()`;
+    return { name, schema };
+};
+/** Zod chain for a projection-specific (added/overriding) field. */
+const overrideFieldSchema = (ir, field) => {
+    const name = isRelation(field) ? relationFkName(field) : field.name;
+    let base;
+    if (field.type.kind === 'enum') {
+        const irEnum = findEnum(ir, field.type.name);
+        base = irEnum ? `${fsEnumName(irEnum)}Schema` : 'z.string()';
+    }
+    else if (field.type.kind === 'scalar')
+        base = SCALAR_FS[field.type.name];
+    else if (field.type.kind === 'model')
+        base = `${fsModelName(ir, field.type.name)}Schema`;
+    else
+        base = 'z.unknown()';
+    let schema = field.list ? `z.array(${base})` : base;
+    if (field.default !== undefined)
+        schema = `${schema}.default(${JSON.stringify(field.default)})`;
+    if (field.nullable)
+        schema = `${schema}.nullable()`;
+    if (field.optional)
+        schema = `${schema}.optional()`;
+    return { name, schema };
+};
+const effectiveFields = (ir, doc) => {
+    const base = doc.from ? findModel(ir, doc.from) : undefined;
+    let baseFields = base?.fields ?? [];
+    if (doc.pick.length > 0) {
+        // Pick order is authoritative for the projected field order.
+        baseFields = doc.pick
+            .map(name => baseFields.find(field => field.name === name))
+            .filter((field) => Boolean(field));
+    }
+    else if (doc.omit.length > 0) {
+        baseFields = baseFields.filter(field => !doc.omit.includes(field.name));
+    }
+    // Insertion order = base fields, then added/overriding fields (override keeps position).
+    const entries = new Map();
+    const roots = [];
+    for (const field of baseFields) {
+        const { name, schema } = baseFieldSchema(ir, field);
+        const pickable = dcFieldChain(ir, field) === schema;
+        entries.set(name, { comments: [], entry: `  ${name}: ${schema},`, name, pickable });
+        roots.push(field);
+    }
+    for (const field of doc.fields) {
+        const { name, schema } = overrideFieldSchema(ir, field);
+        const comments = field.jsdoc ? jsdoc(field.description, '  ') : lineComments(field.description, '  ');
+        entries.set(name, { comments, entry: `  ${name}: ${schema},`, name, pickable: false });
+        roots.push(field);
+    }
+    return { rendered: [...entries.values()], roots };
+};
+const docModuleName = (doc) => camelCase(pluralize(doc.name));
+/**
+ * Split variant of the Firestore projection generator, mirroring the
+ * hand-maintained `libs/types/src/schema/firestore/*` layout: one file per
+ * projection at `firestore/<collectionName>.ts`, FS-only enums (frozen consts)
+ * and embedded value objects co-located at their first referencing projection,
+ * the `_meta_` envelope under `firestore/_/`, and a `firestore.ts` barrel that
+ * also carries the `FIRESTORE_DATABASES` constants.
+ */
+export const createFirestoreSplitGenerator = () => ({
+    name: 'firestore-split',
+    description: 'Firestore projection Zod schemas, one file per collection (firestore/<name>.ts + firestore.ts barrel)',
+    generate(ir, context) {
+        if (ir.firestore.length === 0)
+            return [];
+        const files = [];
+        // Co-locate each referenced enum / embedded model at its first referencing doc.
+        const enumHome = new Map();
+        const modelHome = new Map();
+        const docDeps = new Map();
+        for (const doc of ir.firestore) {
+            const { roots } = effectiveFields(ir, doc);
+            const pseudo = { name: `__${doc.name}`, fields: roots, key: [], indexes: [] };
+            const collected = collectDeps(ir, [pseudo]);
+            const included = (doc.include ?? []).filter(name => !collected.models.includes(name));
+            const deps = { enums: collected.enums, models: [...included, ...collected.models] };
+            docDeps.set(doc.name, deps);
+            const moduleName = docModuleName(doc);
+            for (const name of deps.enums)
+                if (!enumHome.has(name))
+                    enumHome.set(name, moduleName);
+            for (const name of deps.models)
+                if (!modelHome.has(name))
+                    modelHome.set(name, moduleName);
+        }
+        for (const doc of ir.firestore) {
+            const moduleName = docModuleName(doc);
+            const deps = docDeps.get(doc.name) ?? { enums: [], models: [] };
+            const blocks = [...headerBlocks(context), "import { z } from 'zod'"];
+            // Sibling imports: _meta_ plus enums/embedded schemas hosted elsewhere.
+            const external = new Map();
+            for (const name of deps.enums) {
+                const home = enumHome.get(name);
+                if (home && home !== moduleName) {
+                    const irEnum = findEnum(ir, name);
+                    const set = external.get(home) ?? new Set();
+                    set.add(`${irEnum ? fsEnumName(irEnum) : name}Schema`);
+                    external.set(home, set);
+                }
+            }
+            for (const name of deps.models) {
+                const home = modelHome.get(name);
+                if (home && home !== moduleName) {
+                    const set = external.get(home) ?? new Set();
+                    set.add(`${fsModelName(ir, name)}Schema`);
+                    external.set(home, set);
+                }
+            }
+            const importLines = [...external.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([home, symbols]) => `import { ${[...symbols].sort().join(', ')} } from './${home}'`);
+            if (doc.meta)
+                importLines.unshift(`import { _Meta_Schema } from './_'`);
+            // Fields whose Zod chain is identical to the Data Connect schema are
+            // picked from it (single definition); only representation changes extend.
+            const baseModel = doc.from ? findModel(ir, doc.from) : undefined;
+            const { rendered } = effectiveFields(ir, doc);
+            const pickNames = baseModel ? rendered.filter(f => f.pickable).map(f => f.name) : [];
+            if (baseModel && pickNames.length > 0) {
+                importLines.unshift(`import { ${baseModel.name}Schema as Dc${baseModel.name}Schema } from '../schemas/${kebabCase(tableNameOf(baseModel))}'`);
+            }
+            if (importLines.length > 0)
+                blocks.push(importLines.join('\n'));
+            for (const name of deps.enums) {
+                if (enumHome.get(name) !== moduleName)
+                    continue;
+                const irEnum = findEnum(ir, name);
+                if (irEnum)
+                    blocks.push(renderFsEnum(irEnum));
+            }
+            for (const name of deps.models) {
+                if (modelHome.get(name) !== moduleName)
+                    continue;
+                const model = findModel(ir, name);
+                if (model)
+                    blocks.push(renderEmbeddedModel(ir, model));
+            }
+            if (doc.helpers)
+                blocks.push(doc.helpers);
+            const lines = [];
+            if (doc.collection)
+                lines.push(`// ${doc.collection}`);
+            lines.push(...lineComments(doc.description, ''));
+            if (baseModel && pickNames.length > 0) {
+                // DC スキーマと同一表現のフィールドは pick で流用し、FS で表現が変わる
+                // もの（timestamp→Date, optional→nullable, encode 済み id 等）だけ extend する。
+                lines.push(`export const ${doc.name}Schema = Dc${baseModel.name}Schema.pick({`);
+                for (const name of pickNames)
+                    lines.push(`  ${name}: true,`);
+                lines.push(`}).extend({`);
+                for (const field of rendered) {
+                    if (field.pickable)
+                        continue;
+                    lines.push(...field.comments);
+                    lines.push(field.entry);
+                }
+                if (doc.meta)
+                    lines.push('  _meta_: _Meta_Schema,');
+                lines.push('})');
+            }
+            else {
+                lines.push(`export const ${doc.name}Schema = z.object({`);
+                for (const field of rendered) {
+                    lines.push(...field.comments);
+                    lines.push(field.entry);
+                }
+                if (doc.meta)
+                    lines.push('  _meta_: _Meta_Schema,');
+                lines.push('})');
+            }
+            lines.push(`export type ${doc.name} = z.infer<typeof ${doc.name}Schema>`);
+            blocks.push(lines.join('\n'));
+            files.push({ path: `firestore/${moduleName}.ts`, content: `${blocks.join('\n\n')}\n` });
+        }
+        if (ir.firestore.some(doc => doc.meta)) {
+            files.push({ path: 'firestore/_/_meta_.ts', content: META_FILE });
+            files.push({ path: 'firestore/_/index.ts', content: `export * from './_meta_'\n` });
+        }
+        // Barrel: database name constants (when the project defines services) + re-exports.
+        const barrel = [...headerBlocks(context)];
+        const services = ir.project?.services ?? [];
+        if (services.length > 0) {
+            const entries = services.map(s => `  ${constantCase(s.name)}: ${singleQuote(s.database ?? s.name)},`);
+            barrel.push([
+                '/** Firestore database 名定数 (firebase.json と同期させること) */',
+                'export const FIRESTORE_DATABASES = Object.freeze({',
+                ...entries,
+                '} as const)',
+                'export type FirestoreDatabaseKey = keyof typeof FIRESTORE_DATABASES',
+                'export type FirestoreDatabaseId = (typeof FIRESTORE_DATABASES)[FirestoreDatabaseKey]',
+            ].join('\n'));
+        }
+        const exportLines = ir.firestore.map(doc => `export * from './firestore/${docModuleName(doc)}'`);
+        if (ir.firestore.some(doc => doc.meta))
+            exportLines.push(`export * from './firestore/_'`);
+        barrel.push(['// Zod schema / TypeScript 型のエクスポート', ...exportLines].join('\n'));
+        files.push({ path: 'firestore.ts', content: `${barrel.join('\n\n')}\n` });
+        return files;
+    },
+});

package/dist/lib/_internal/generators/firestore/firestore-type-generator.d.ts

@@ -0,0 +1,12 @@
+import { Generator } from '../generator.js';
+export interface FirestoreGeneratorOptions {
+    /** Module to import `Timestamp` from. Defaults to `firebase/firestore`. */
+    timestampImport?: string;
+}
+/**
+ * Generates Firestore-oriented TypeScript document types: `timestamp`/`date`
+ * map to the Firestore `Timestamp` class and each model gets a `WithId` helper
+ * for reading documents that carry their id.
+ */
+export declare const createFirestoreTypeGenerator: (options?: FirestoreGeneratorOptions) => Generator;
+//# sourceMappingURL=firestore-type-generator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-type-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/firestore/firestore-type-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAI5E,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AA0DD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAS,yBAA8B,KAAG,SAiCtF,CAAA"}

package/dist/lib/_internal/generators/firestore/firestore-type-generator.js

@@ -0,0 +1,81 @@
+import { headerBlocks } from '../support/header.js';
+import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
+const scalarMap = () => ({
+    string: 'string',
+    int: 'number',
+    int64: 'number',
+    float: 'number',
+    boolean: 'boolean',
+    timestamp: 'Timestamp',
+    date: 'Timestamp',
+    json: 'Json',
+    id: 'string',
+});
+const JSON_TYPE = [
+    'export type Json =',
+    '  | string',
+    '  | number',
+    '  | boolean',
+    '  | null',
+    '  | Json[]',
+    '  | { [key: string]: Json }',
+].join('\n');
+const renderRef = (ref, scalars) => {
+    switch (ref.kind) {
+        case 'scalar':
+            return scalars[ref.name];
+        case 'enum':
+        case 'model':
+            return ref.name;
+        default:
+            return 'unknown';
+    }
+};
+const renderField = (field, scalars, ir) => {
+    const optional = field.optional ? '?' : '';
+    const doc = field.description ? `  /** ${field.description} */\n` : '';
+    // Firestore projections store relations as resolved foreign-key ids.
+    if (isRelation(field)) {
+        const base = scalars[relationFkType(ir, field)];
+        const type = field.list ? `${base}[]` : base;
+        return `${doc}  ${relationFkName(field)}${optional}: ${type}`;
+    }
+    const base = renderRef(field.type, scalars);
+    const type = field.list ? `${base}[]` : base;
+    return `${doc}  ${field.name}${optional}: ${type}`;
+};
+const usesTimestamp = (ir) => ir.models.some(model => model.fields.some(field => field.type.kind === 'scalar' && (field.type.name === 'timestamp' || field.type.name === 'date')));
+const usesJson = (ir) => ir.models.some(model => model.fields.some(field => field.type.kind === 'scalar' && field.type.name === 'json'));
+/**
+ * Generates Firestore-oriented TypeScript document types: `timestamp`/`date`
+ * map to the Firestore `Timestamp` class and each model gets a `WithId` helper
+ * for reading documents that carry their id.
+ */
+export const createFirestoreTypeGenerator = (options = {}) => {
+    const timestampImport = options.timestampImport ?? 'firebase/firestore';
+    const scalars = scalarMap();
+    return {
+        name: 'firestore-types',
+        description: 'Firestore document TypeScript types',
+        generate(ir, context) {
+            const blocks = [...headerBlocks(context)];
+            if (usesTimestamp(ir)) {
+                blocks.push(`import { Timestamp } from '${timestampImport}'`);
+            }
+            if (usesJson(ir)) {
+                blocks.push(JSON_TYPE);
+            }
+            blocks.push('export type WithId<T> = T & { id: string }');
+            for (const irEnum of ir.enums) {
+                const union = irEnum.values.map(value => `'${value}'`).join(' | ') || 'never';
+                blocks.push(`export type ${irEnum.name} = ${union}`);
+            }
+            for (const model of ir.models) {
+                const doc = model.description ? `/** ${model.description} */\n` : '';
+                const fields = model.fields.map(field => renderField(field, scalars, ir)).join('\n');
+                blocks.push(`${doc}export interface ${model.name} {\n${fields}\n}`);
+            }
+            return [{ path: 'firestore-types.ts', content: `${blocks.join('\n\n')}\n` }];
+        },
+    };
+};

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

@@ -0,0 +1,23 @@
+import { Ir } from '../ir/ir.js';
+export interface GeneratedFile {
+    /** Path relative to the generation output directory. */
+    path: string;
+    content: string;
+}
+export interface GeneratorContext {
+    /** Optional banner prepended to each generated file. */
+    header?: string;
+}
+/**
+ * A code generator turns the IR into one or more output files. Implementations
+ * MUST depend only on the IR — never on YAML, raw documents, other generators,
+ * or shared mutable state. That independence is what lets generators be added,
+ * removed, or run in isolation.
+ */
+export interface Generator {
+    /** Unique key used to select the generator from the CLI/registry. */
+    readonly name: string;
+    readonly description?: string;
+    generate(ir: Ir, context?: GeneratorContext): GeneratedFile[];
+}
+//# sourceMappingURL=generator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/generators/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAEhC,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAAA;CAC9D"}

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

@@ -0,0 +1 @@
+export {};

package/dist/lib/_internal/generators/id/id-codec-generator.d.ts

@@ -0,0 +1,16 @@
+import { Generator } from '../generator.js';
+export interface IdCodecGeneratorOptions {
+    /**
+     * Module the generic `encodeNumericId`/`decodeNumericId`/`encodeStringId`/
+     * `decodeStringId` primitives are imported from. Defaults to `./id-core.js`.
+     */
+    core?: string;
+}
+/**
+ * Generates typed per-entity id encode/decode wrappers (`encodeShopId`,
+ * `decodeProductId`, …) over the generic Sqids/hashids primitives — instead of
+ * scattering untyped `encodeNumericId` calls at every call site, the wrappers
+ * make the int↔string boundary explicit and entity-safe.
+ */
+export declare const createIdCodecGenerator: (options?: IdCodecGeneratorOptions) => Generator;
+//# sourceMappingURL=id-codec-generator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"id-codec-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/id/id-codec-generator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAG5E,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AA2GD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAS,uBAA4B,KAAG,SA8B9E,CAAA"}

package/dist/lib/_internal/generators/id/id-codec-generator.js

@@ -0,0 +1,140 @@
+import { pascalCase } from '../support/naming.js';
+import { headerBlocks } from '../support/header.js';
+const idFieldOf = (model) => {
+    const ids = model.fields.filter(field => field.isId);
+    return ids.length === 1 ? ids[0] : undefined;
+};
+/** Numeric (Int64/bigserial) ids use the numeric codec; everything else the string codec. */
+const isNumericId = (field) => field.type.kind === 'scalar' && (field.type.name === 'int' || field.type.name === 'int64');
+/**
+ * Self-contained Sqids primitives, emitted when the contract configures
+ * `project.idCodec`, so the Sqids alphabet/minLength stay a contract-level
+ * constant shared by every service.
+ */
+const idCoreFile = (idCodec) => `import Sqids from 'sqids'
+
+/**
+ * ID 短縮用の Sqids インスタンス
+ *
+ * minLength: 最小${idCodec.minLength ?? 8}文字（短すぎないように）
+ * alphabet: URL-safe な文字のみ（シャッフル済み）
+ */
+const sqids = new Sqids({
+  minLength: ${idCodec.minLength ?? 8},
+  alphabet: '${idCodec.alphabet ?? ''}',
+})
+
+/**
+ * 数値 ID（DC の BIGINT 等）を Sqids でエンコードして短い URL-safe 文字列にする。
+ *
+ * @param id - 数値 ID（string 形式の数値、JS の safe integer 範囲内）
+ * @returns 短縮文字列
+ * @throws safe integer 範囲を超える場合
+ */
+export const encodeNumericId = (id: string): string => {
+  if (id === '') {
+    throw new Error('Cannot encode empty ID')
+  }
+  const numId = Number(id)
+  if (!Number.isSafeInteger(numId)) {
+    throw new Error(\`ID exceeds safe integer range: \${id}\`)
+  }
+  return sqids.encode([numId])
+}
+
+/**
+ * \`encodeNumericId\` でエンコードされた文字列を元の数値文字列に戻す。
+ *
+ * @param encoded - encodeNumericId の出力
+ * @returns DC の ID（string 形式）
+ * @throws デコードできない場合
+ */
+export const decodeNumericId = (encoded: string): string => {
+  const decoded = sqids.decode(encoded)
+  const value = decoded[0]
+  if (value === undefined) {
+    throw new Error(\`Invalid encoded numeric ID: \${encoded}\`)
+  }
+  return value.toString()
+}
+
+/**
+ * 任意の文字列を Sqids でエンコードする。
+ *
+ * 文字列の各コードポイント (UTF-16 サロゲートペアも 1 文字として扱う) を
+ * 数値配列に変換し、 sqids にかける。 結果は URL-safe な短縮文字列。
+ *
+ * 用途: Firebase uid のような英数字 ID を、 数値 ID と同じ枠組みで扱いたいとき。
+ * 文字列長に比例して結果も長くなるので、 短縮効果は薄い (難読化が主目的)。
+ */
+export const encodeStringId = (str: string): string => {
+  if (str === '') {
+    throw new Error('Cannot encode empty string')
+  }
+  const codePoints = Array.from(str).map(c => c.codePointAt(0) ?? 0)
+  return sqids.encode(codePoints)
+}
+
+/**
+ * \`encodeStringId\` でエンコードされた文字列を元の文字列に戻す。
+ *
+ * @throws デコードできない場合
+ */
+export const decodeStringId = (encoded: string): string => {
+  const codePoints = sqids.decode(encoded)
+  if (codePoints.length === 0) {
+    throw new Error(\`Invalid encoded string ID: \${encoded}\`)
+  }
+  return String.fromCodePoint(...codePoints)
+}
+`;
+const renderCodec = (model, field) => {
+    const name = pascalCase(model.name);
+    if (isNumericId(field)) {
+        return [
+            `export const encode${name}Id = (id: number | string): string => encodeNumericId(String(id))`,
+            `export const decode${name}Id = (encoded: string): string => decodeNumericId(encoded)`,
+        ].join('\n');
+    }
+    return [
+        `export const encode${name}Id = (id: string): string => encodeStringId(id)`,
+        `export const decode${name}Id = (encoded: string): string => decodeStringId(encoded)`,
+    ].join('\n');
+};
+/**
+ * Generates typed per-entity id encode/decode wrappers (`encodeShopId`,
+ * `decodeProductId`, …) over the generic Sqids/hashids primitives — instead of
+ * scattering untyped `encodeNumericId` calls at every call site, the wrappers
+ * make the int↔string boundary explicit and entity-safe.
+ */
+export const createIdCodecGenerator = (options = {}) => {
+    const core = options.core ?? './id-core.js';
+    return {
+        name: 'id-codecs',
+        description: 'Typed per-entity id encode/decode wrappers',
+        generate(ir, context) {
+            const entries = ir.models
+                .map(model => ({ model, field: idFieldOf(model) }))
+                .filter((entry) => !!entry.field);
+            if (entries.length === 0) {
+                return [];
+            }
+            const needsNumeric = entries.some(e => isNumericId(e.field));
+            const needsString = entries.some(e => !isNumericId(e.field));
+            const imports = [
+                ...(needsNumeric ? ['encodeNumericId', 'decodeNumericId'] : []),
+                ...(needsString ? ['encodeStringId', 'decodeStringId'] : []),
+            ];
+            const blocks = [...headerBlocks(context), `import { ${imports.join(', ')} } from '${core}'`];
+            for (const { model, field } of entries) {
+                blocks.push(renderCodec(model, field));
+            }
+            const files = [{ path: 'id-codecs.ts', content: `${blocks.join('\n\n')}\n` }];
+            // Emit the primitives too when the contract pins the Sqids settings.
+            if (ir.project?.idCodec && core === './id-core.js') {
+                files.push({ path: 'id-core.ts', content: idCoreFile(ir.project.idCodec) });
+            }
+            return files;
+        },
+    };
+};