@omnifyjp/omnify 3.12.5 → 3.13.1

package/ts-dist/payload-builder-generator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @omnify/ts — Payload Builder Generator (issue omnify-jp/omnify-go#55)
+ *
+ * Emits per-model form-state interfaces and payload-builder helpers
+ * alongside the existing zod schemas. Translatable fields are typed as
+ * `Record<Locale, string>` in the form state (matching the design
+ * system's `<Input translatable />` component shape) and the builder
+ * collapses them into the nested locale-keyed payload that the create /
+ * update zod schemas accept (see issue #53).
+ *
+ * Output (added to base/<Model>.ts):
+ *
+ *   export interface <Model>CreateFormState  { ... }
+ *   export interface <Model>UpdateFormState  { ... }
+ *   export function empty<Model>CreateForm() { ... }
+ *   export function build<Model>CreatePayload(form) { ... }
+ *   export function build<Model>UpdatePayload(form) { ... }
+ *
+ * The shared `buildI18nPayload` utility is emitted exactly once at the
+ * codegen output root in `payload-helpers.ts` so per-model files can
+ * import it.
+ */
+import type { GeneratorOptions, SchemaDefinition } from './types.js';
+import { type MetadataFieldType } from './metadata-generator.js';
+/** A single field as seen by the form-state / payload builder. */
+export interface FormField {
+    /** Field key as it appears on the wire (snake_case, with `_id` suffix on FKs). */
+    fieldName: string;
+    /** TypeScript primitive used in the form-state interface. */
+    tsType: string;
+    /** Coarse type taxonomy from the metadata generator. */
+    metaType: MetadataFieldType;
+    /** Whether the YAML declared the field translatable. */
+    translatable: boolean;
+    /** Whether the field is required by the create schema. */
+    required: boolean;
+    /** Whether the YAML declared the field nullable. */
+    nullable: boolean;
+    /** Default value for `empty<Model>CreateForm()`, as a JS literal string. */
+    defaultLiteral: string;
+    /**
+     * When true, the field is intentionally omitted from the
+     * `empty<Model>CreateForm()` factory body. Used for optional enum
+     * reference fields where no sensible default exists — the interface
+     * marks the field `?:` so omitting the key is valid, and this is
+     * safer than emitting `undefined` under `exactOptionalPropertyTypes`.
+     * Issue omnify-jp/omnify-go#56.
+     */
+    omitFromEmpty?: boolean;
+}
+/** Resolved per-schema form metadata. */
+export interface SchemaFormShape {
+    modelName: string;
+    fields: FormField[];
+}
+/** Build the form shape IR from a schema. */
+export declare function buildFormShape(schema: SchemaDefinition, allSchemas: Record<string, SchemaDefinition>, options: GeneratorOptions): SchemaFormShape;
+/** Render the full payload-builder section for a schema. */
+export declare function formatPayloadBuilderSection(shape: SchemaFormShape, defaultLocale: string): string;

package/ts-dist/payload-builder-generator.js

@@ -0,0 +1,339 @@
+/**
+ * @omnify/ts — Payload Builder Generator (issue omnify-jp/omnify-go#55)
+ *
+ * Emits per-model form-state interfaces and payload-builder helpers
+ * alongside the existing zod schemas. Translatable fields are typed as
+ * `Record<Locale, string>` in the form state (matching the design
+ * system's `<Input translatable />` component shape) and the builder
+ * collapses them into the nested locale-keyed payload that the create /
+ * update zod schemas accept (see issue #53).
+ *
+ * Output (added to base/<Model>.ts):
+ *
+ *   export interface <Model>CreateFormState  { ... }
+ *   export interface <Model>UpdateFormState  { ... }
+ *   export function empty<Model>CreateForm() { ... }
+ *   export function build<Model>CreatePayload(form) { ... }
+ *   export function build<Model>UpdatePayload(form) { ... }
+ *
+ * The shared `buildI18nPayload` utility is emitted exactly once at the
+ * codegen output root in `payload-helpers.ts` so per-model files can
+ * import it.
+ */
+import { toSnakeCase } from './interface-generator.js';
+import { classifyFieldType } from './metadata-generator.js';
+import { toEnumMemberName } from './enum-generator.js';
+// ---------------------------------------------------------------------------
+// Build the IR
+// ---------------------------------------------------------------------------
+const PRIMITIVE_TS_DEFAULTS = {
+    string: "''",
+    text: "''",
+    number: '0',
+    boolean: 'false',
+    date: "''",
+    datetime: "''",
+    time: "''",
+    json: 'null',
+    enum: "''",
+    uuid: "''",
+    file: 'null',
+    compound: "''",
+};
+function tsTypeForField(metaType, prop) {
+    switch (metaType) {
+        case 'string':
+        case 'text':
+        case 'date':
+        case 'datetime':
+        case 'time':
+        case 'uuid':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'json':
+            return 'unknown';
+        case 'file':
+            return 'unknown';
+        case 'enum':
+            // Use the enum reference name when available so downstream form
+            // components get type narrowing on the union.
+            if (typeof prop.enum === 'string')
+                return prop.enum;
+            if (Array.isArray(prop.enum)) {
+                return prop.enum
+                    .map((v) => `'${typeof v === 'string' ? v : v.value}'`)
+                    .join(' | ');
+            }
+            return 'string';
+        default:
+            return 'string';
+    }
+}
+/**
+ * Resolve an enum's value list either from a plugin enum bank
+ * (customTypes.enums) or from a schema-defined enum (`kind: enum` schemas).
+ * Returns undefined if the enum reference can't be resolved at codegen time.
+ */
+function resolveEnumValueList(prop, allSchemas, pluginEnums) {
+    if (typeof prop.enum === 'string') {
+        // Plugin enum first (customTypes.enums), then schema enum.
+        const fromPlugin = pluginEnums[prop.enum];
+        if (fromPlugin)
+            return fromPlugin;
+        const schemaEnum = allSchemas[prop.enum];
+        if (schemaEnum?.values && schemaEnum.values.length > 0) {
+            return schemaEnum.values.map((v) => v.value);
+        }
+        return undefined;
+    }
+    if (Array.isArray(prop.enum)) {
+        return prop.enum.map((v) => typeof v === 'string' ? v : v.value);
+    }
+    return undefined;
+}
+function defaultLiteralForField(metaType, prop, required, allSchemas, pluginEnums) {
+    // -----------------------------------------------------------------
+    // Enum fields — reference the enum member, not a string literal.
+    //
+    // `status: 'free'` is not assignable to `TableStatus` under strict
+    // TypeScript because enum types are nominal. We must emit
+    // `TableStatus.Free` instead. For inline enums (array of strings) the
+    // TS type is a literal union, so string literals are fine — that case
+    // falls through to the JSON.stringify path at the bottom.
+    //
+    // Issue omnify-jp/omnify-go#56.
+    // -----------------------------------------------------------------
+    if (metaType === 'enum' && typeof prop.enum === 'string') {
+        const enumName = prop.enum;
+        // Optional / nullable enum refs: omit from the factory body entirely.
+        // The form-state interface already marks the field `?:`, so skipping
+        // the key is a valid object literal under strict TS regardless of
+        // `exactOptionalPropertyTypes`.
+        if (!required) {
+            return { literal: '', omit: true };
+        }
+        // Pick the default value: honor YAML `default` first, else first
+        // declared enum member.
+        let rawValue;
+        if (prop.default !== undefined && prop.default !== null) {
+            rawValue = String(prop.default);
+        }
+        else {
+            const values = resolveEnumValueList(prop, allSchemas, pluginEnums);
+            if (values && values.length > 0) {
+                rawValue = values[0];
+            }
+        }
+        if (rawValue === undefined) {
+            // Can't resolve the enum values at codegen time (unlikely, but
+            // keeps the generator total). Fall back to omitting — the dev
+            // will get a TS error at form init and can fix it manually.
+            return { literal: '', omit: true };
+        }
+        return { literal: `${enumName}.${toEnumMemberName(rawValue)}` };
+    }
+    // Honor an explicit YAML default when present (non-enum path).
+    if (prop.default !== undefined && prop.default !== null) {
+        return { literal: JSON.stringify(prop.default) };
+    }
+    // Inline enum (array form) — the form-state tsType is a literal union,
+    // so a string literal is directly assignable. Use the first value.
+    if (metaType === 'enum') {
+        if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+            const first = prop.enum[0];
+            const val = typeof first === 'string' ? first : first.value;
+            return { literal: JSON.stringify(val) };
+        }
+        return { literal: "''" };
+    }
+    if (metaType === 'boolean')
+        return { literal: 'false' };
+    return { literal: PRIMITIVE_TS_DEFAULTS[metaType] };
+}
+/** Build the form shape IR from a schema. */
+export function buildFormShape(schema, allSchemas, options) {
+    const fields = [];
+    if (!schema.properties) {
+        return { modelName: schema.name, fields };
+    }
+    const propNames = schema.propertyOrder ?? Object.keys(schema.properties);
+    for (const propName of propNames) {
+        const prop = schema.properties[propName];
+        if (!prop)
+            continue;
+        // Skip inverse-side associations — they have no column.
+        if (prop.type === 'Association' &&
+            (prop.mappedBy || prop.relation === 'OneToMany' ||
+                prop.relation === 'ManyToMany' || prop.relation === 'MorphMany' ||
+                prop.relation === 'MorphTo' || prop.relation === 'MorphToMany' ||
+                prop.relation === 'MorphedByMany')) {
+            continue;
+        }
+        // Skip File for the form-state shape — file uploads have a different
+        // lifecycle (multipart form, temp tokens) handled outside the JSON
+        // payload builder.
+        if (prop.type === 'File')
+            continue;
+        const metaType = classifyFieldType(prop, allSchemas, options.customTypes.simple);
+        const isOwningAssoc = prop.type === 'Association' &&
+            (prop.relation === 'ManyToOne' || prop.relation === 'OneToOne') &&
+            !prop.mappedBy;
+        const fieldName = isOwningAssoc
+            ? `${toSnakeCase(propName)}_id`
+            : toSnakeCase(propName);
+        // rules.required overrides nullable inference
+        const required = prop.rules?.required === false
+            ? false
+            : prop.rules?.required === true
+                ? true
+                : !(prop.nullable ?? false);
+        const { literal, omit } = defaultLiteralForField(metaType, prop, required, allSchemas, options.customTypes.enums);
+        fields.push({
+            fieldName,
+            tsType: tsTypeForField(metaType, prop),
+            metaType,
+            translatable: prop.translatable === true,
+            required,
+            nullable: prop.nullable ?? false,
+            defaultLiteral: literal,
+            omitFromEmpty: omit,
+        });
+    }
+    return { modelName: schema.name, fields };
+}
+// ---------------------------------------------------------------------------
+// Format the form-state interfaces + builder helpers
+// ---------------------------------------------------------------------------
+/** Render the full payload-builder section for a schema. */
+export function formatPayloadBuilderSection(shape, defaultLocale) {
+    const { modelName, fields } = shape;
+    if (fields.length === 0)
+        return '';
+    const parts = [];
+    parts.push(`// ============================================================================\n`);
+    parts.push(`// Form State + Payload Builders (issue #55)\n`);
+    parts.push(`// ============================================================================\n\n`);
+    // ---- Create form state interface ----
+    parts.push(`/** Form-state shape for creating a ${modelName}. Translatable fields are\n` +
+        ` *  flat per-locale maps; the builder collapses them into the wire shape. */\n`);
+    parts.push(`export interface ${modelName}CreateFormState {\n`);
+    for (const f of fields) {
+        if (f.translatable) {
+            parts.push(`  ${f.fieldName}: Record<Locale, string>;\n`);
+        }
+        else {
+            const optional = !f.required;
+            parts.push(`  ${f.fieldName}${optional ? '?' : ''}: ${f.tsType}${f.nullable ? ' | null' : ''};\n`);
+        }
+    }
+    parts.push(`}\n\n`);
+    // ---- Update form state interface ----
+    parts.push(`/** Form-state shape for updating a ${modelName}. Every field optional. */\n`);
+    parts.push(`export interface ${modelName}UpdateFormState {\n`);
+    for (const f of fields) {
+        if (f.translatable) {
+            parts.push(`  ${f.fieldName}?: Record<Locale, string>;\n`);
+        }
+        else {
+            parts.push(`  ${f.fieldName}?: ${f.tsType}${f.nullable ? ' | null' : ''};\n`);
+        }
+    }
+    parts.push(`}\n\n`);
+    // ---- empty<Model>CreateForm factory ----
+    parts.push(`/** Default-state factory for the create form. Pre-fills every locale key. */\n`);
+    parts.push(`export function empty${modelName}CreateForm(): ${modelName}CreateFormState {\n`);
+    parts.push(`  return {\n`);
+    for (const f of fields) {
+        // Skip fields marked for omission (e.g. optional enum references
+        // with no sensible default — the interface marks them `?:`).
+        // Issue omnify-jp/omnify-go#56.
+        if (f.omitFromEmpty)
+            continue;
+        if (f.translatable) {
+            parts.push(`    ${f.fieldName}: emptyLocaleMap(),\n`);
+        }
+        else {
+            parts.push(`    ${f.fieldName}: ${f.defaultLiteral},\n`);
+        }
+    }
+    parts.push(`  };\n`);
+    parts.push(`}\n\n`);
+    // ---- buildCreatePayload ----
+    parts.push(`/** Convert create form state into the payload that ` +
+        `base${modelName}CreateSchema accepts. */\n`);
+    parts.push(`export function build${modelName}CreatePayload(form: ${modelName}CreateFormState): Base${modelName}Create {\n`);
+    // Field-by-field assignment.
+    parts.push(`  const payload: Record<string, unknown> = {\n`);
+    for (const f of fields) {
+        if (f.translatable) {
+            // Top-level mirror = default-locale value, trimmed.
+            parts.push(`    ${f.fieldName}: (form.${f.fieldName}[${JSON.stringify(defaultLocale)}] ?? '').trim(),\n`);
+        }
+        else if (f.metaType === 'string' || f.metaType === 'text' || f.metaType === 'uuid') {
+            if (f.required) {
+                parts.push(`    ${f.fieldName}: form.${f.fieldName}.trim(),\n`);
+            }
+            else {
+                // Drop empty optional strings.
+                parts.push(`    ${f.fieldName}: form.${f.fieldName}?.toString().trim() || ${f.nullable ? 'null' : 'undefined'},\n`);
+            }
+        }
+        else if (f.metaType === 'date' || f.metaType === 'datetime') {
+            // Already a string in form state; pass through.
+            parts.push(`    ${f.fieldName}: form.${f.fieldName},\n`);
+        }
+        else {
+            parts.push(`    ${f.fieldName}: form.${f.fieldName},\n`);
+        }
+    }
+    parts.push(`  };\n\n`);
+    // Spread per-locale sub-objects (issue #53 wire shape).
+    const translatableFieldNames = fields.filter((f) => f.translatable).map((f) => f.fieldName);
+    if (translatableFieldNames.length > 0) {
+        parts.push(`  // Per-locale sub-objects (matches issue #53 wire shape).\n`);
+        parts.push(`  const i18n = buildI18nPayload({\n`);
+        for (const name of translatableFieldNames) {
+            parts.push(`    ${name}: form.${name},\n`);
+        }
+        parts.push(`  });\n`);
+        parts.push(`  Object.assign(payload, i18n);\n\n`);
+    }
+    parts.push(`  return payload as Base${modelName}Create;\n`);
+    parts.push(`}\n\n`);
+    // ---- buildUpdatePayload ----
+    parts.push(`/** Convert update form state into the payload that ` +
+        `base${modelName}UpdateSchema accepts. Only fields present on \`form\` are emitted. */\n`);
+    parts.push(`export function build${modelName}UpdatePayload(form: ${modelName}UpdateFormState): Base${modelName}Update {\n`);
+    parts.push(`  const payload: Record<string, unknown> = {};\n`);
+    for (const f of fields) {
+        if (f.translatable) {
+            parts.push(`  if (form.${f.fieldName} !== undefined) {\n`);
+            parts.push(`    payload.${f.fieldName} = (form.${f.fieldName}[${JSON.stringify(defaultLocale)}] ?? '').trim();\n`);
+            parts.push(`  }\n`);
+        }
+        else if (f.metaType === 'string' || f.metaType === 'text' || f.metaType === 'uuid') {
+            parts.push(`  if (form.${f.fieldName} !== undefined) {\n`);
+            parts.push(`    payload.${f.fieldName} = form.${f.fieldName}?.toString().trim() ?? null;\n`);
+            parts.push(`  }\n`);
+        }
+        else {
+            parts.push(`  if (form.${f.fieldName} !== undefined) {\n`);
+            parts.push(`    payload.${f.fieldName} = form.${f.fieldName};\n`);
+            parts.push(`  }\n`);
+        }
+    }
+    if (translatableFieldNames.length > 0) {
+        parts.push(`\n  // Per-locale sub-objects only for fields the user touched.\n`);
+        parts.push(`  const localeInput: Record<string, Record<string, string> | undefined> = {};\n`);
+        for (const name of translatableFieldNames) {
+            parts.push(`  if (form.${name} !== undefined) localeInput.${name} = form.${name};\n`);
+        }
+        parts.push(`  Object.assign(payload, buildI18nPayload(localeInput));\n`);
+    }
+    parts.push(`  return payload as Base${modelName}Update;\n`);
+    parts.push(`}\n`);
+    return parts.join('');
+}

package/ts-dist/zod-generator.d.ts

@@ -25,7 +25,7 @@ export declare function getExcludedFields(schema: SchemaDefinition): {
 export declare function formatZodSchemasSection(schemaName: string, zodSchemas: ZodPropertySchema[], displayNames: SchemaDisplayNames, excludedFields: {
     create: Set<string>;
     update: Set<string>;
-}): string;
+}, schema: SchemaDefinition, options: GeneratorOptions): string;
 /**
  * Format user model file with Zod re-exports.
  */

package/ts-dist/zod-generator.js

@@ -409,10 +409,69 @@ export function getExcludedFields(schema) {
     }
     return { create: createExclude, update: updateExclude };
 }
+/**
+ * Build the per-locale sub-object lines for a schema's translatable fields.
+ *
+ * For every property with `translatable: true`, we synthesize a "translation
+ * variant" of its zod schema by forcing `nullable: true` and clearing
+ * `rules.required`. This means:
+ *   - `String` translatable fields drop the implicit `.min(1)` (translation
+ *     rows for non-default locales may legitimately be empty).
+ *   - `max(N)` / `length(N)` validators are preserved so client and server
+ *     agree on bounds.
+ *   - The variant ends in `.optional().nullable()` so missing translations
+ *     don't break validation.
+ *
+ * Each locale (from `options.locales`) gets its own sub-object containing
+ * only the translatable fields. The sub-object itself is `.optional()` so
+ * a payload may omit any locale entirely. Implements omnify-jp/omnify-go#53.
+ *
+ * Returns the lines (without trailing newlines) ready to splice into the
+ * `z.object({ ... })` body of the create schema, or an empty array when
+ * the schema has no translatable fields.
+ */
+function buildTranslatableLocaleSchemaLines(schema, options) {
+    if (!schema.properties || options.locales.length === 0)
+        return [];
+    // Collect translatable fields in declaration order so the generated
+    // sub-object body matches the rest of the file.
+    const translatableProps = [];
+    const propNames = schema.propertyOrder ?? Object.keys(schema.properties);
+    for (const propName of propNames) {
+        const propDef = schema.properties[propName];
+        if (!propDef || !propDef.translatable)
+            continue;
+        // Build the translation variant: nullable, no `required` rule. The
+        // existing zod generator handles the rest (max length, regex, etc.).
+        const variantDef = {
+            ...propDef,
+            nullable: true,
+            rules: propDef.rules ? { ...propDef.rules, required: false } : undefined,
+        };
+        const variantSchema = getZodSchemaForType(variantDef, propName, options);
+        if (!variantSchema)
+            continue;
+        translatableProps.push({
+            fieldName: toSnakeCase(propName),
+            schema: variantSchema,
+        });
+    }
+    if (translatableProps.length === 0)
+        return [];
+    const lines = [];
+    for (const locale of options.locales) {
+        lines.push(`  ${locale}: z.object({`);
+        for (const tp of translatableProps) {
+            lines.push(`    ${tp.fieldName}: ${tp.schema},`);
+        }
+        lines.push(`  }).optional(),`);
+    }
+    return lines;
+}
 /**
  * Format Zod schemas section for a base file.
  */
-export function formatZodSchemasSection(schemaName, zodSchemas, displayNames, excludedFields) {
+export function formatZodSchemasSection(schemaName, zodSchemas, displayNames, excludedFields, schema, options) {
     const parts = [];
     const lowerName = schemaName.charAt(0).toLowerCase() + schemaName.slice(1);
     // I18n section
@@ -451,6 +510,14 @@ export function formatZodSchemasSection(schemaName, zodSchemas, displayNames, ex
     for (const prop of createFields) {
         parts.push(`  ${prop.fieldName}: base${schemaName}Schemas.${prop.fieldName},\n`);
     }
+    // Per-locale sub-objects for translatable fields. The Update schema
+    // (which is `.partial()` of Create) inherits these for free, so the
+    // partial form correctly types each locale key as optional too.
+    // Issue omnify-jp/omnify-go#53.
+    const localeLines = buildTranslatableLocaleSchemaLines(schema, options);
+    for (const line of localeLines) {
+        parts.push(line + '\n');
+    }
     parts.push(`});\n\n`);
     // Update Schema
     parts.push(`/** Update schema for ${schemaName} */\n`);

package/types/config.d.ts

@@ -31,8 +31,10 @@ export interface ConnectionConfig {
 export interface CodegenTypeScriptConfig {
   /** Enable TypeScript codegen. Defaults to false. */
   enable: boolean;
-  /** Output directory for generated TypeScript model files. */
-  modelsPath: string;
+  /** Output directory for generated TypeScript model files (legacy alias for `output`). */
+  modelsPath?: string;
+  /** Output directory for generated TypeScript model files. Preferred over `modelsPath`; symmetrical with the top-level `input` field used by consumer-mode configs. */
+  output?: string;
 }
 
 /** Laravel codegen path configuration for a target (model, request, etc.). */
@@ -107,6 +109,16 @@ export interface PackageConfig {
 
 /** Main Omnify configuration (omnify.yaml). */
 export interface OmnifyConfig {
+  /**
+   * Consumer-mode shortcut: path/URL/npm-spec for an upstream `schemas.json`.
+   * When set, omnify-ts skips the connections+migrations indirection and
+   * uses this value directly. Accepts a local path (relative to this file),
+   * an http(s) URL (cached + pinned via `.omnify/input.lock.json`), or a
+   * scoped npm package specifier (e.g. `@famgia/dxs-product-schemas/schemas.json`).
+   * Frontend / consumer projects should use this; backend projects use
+   * `schemasDir` + `connections` instead.
+   */
+  input?: string;
   /** Directory containing schema YAML files. */
   schemasDir?: string;
   /** External schema packages to consume. */