@omnifyjp/omnify 3.22.1 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.22.1",
+  "version": "3.23.0",
   "description": "Schema-driven code generation for Laravel, TypeScript, and SQL",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
-    "@omnifyjp/omnify-darwin-arm64": "3.22.1",
-    "@omnifyjp/omnify-darwin-x64": "3.22.1",
-    "@omnifyjp/omnify-linux-x64": "3.22.1",
-    "@omnifyjp/omnify-linux-arm64": "3.22.1",
-    "@omnifyjp/omnify-win32-x64": "3.22.1"
+    "@omnifyjp/omnify-darwin-arm64": "3.23.0",
+    "@omnifyjp/omnify-darwin-x64": "3.23.0",
+    "@omnifyjp/omnify-linux-x64": "3.23.0",
+    "@omnifyjp/omnify-linux-arm64": "3.23.0",
+    "@omnifyjp/omnify-win32-x64": "3.23.0"
   }
 }

package/ts-dist/php/service-generator.d.ts

@@ -1,11 +1,29 @@
 /**
- * Generates base + editable service classes for schemas with `options.api`
- * or `options.service`.
+ * Generates base + editable service classes.
  *
  * Issue #57: Full BaseService codegen with translatable, softDelete, audit,
  * DB::transaction, eagerLoad/eagerCount, lookupFields, defaultSort.
+ *
+ * Issue #81 (v3.23.0): convention-over-configuration flip. Services are now
+ * generated by default for every project `kind: object` schema. Opt out with
+ * `options.service: false` (pivots, translation sidecars, audit logs).
+ * Property-level flags (`searchable`, `filterable`, `sortable`, `lookupable`,
+ * `defaultSort: asc|desc`) are the single source of truth — the legacy
+ * `options.service.{searchable,filterable,defaultSort,lookupFields,eagerLoad,
+ * eagerCount}` keys are deprecated and emit warnings at generate time.
  */
 import { SchemaReader } from './schema-reader.js';
 import type { GeneratedFile, PhpConfig } from './types.js';
-/** Generate service classes for all schemas with api or service config. */
+/**
+ * Generate service classes for every project object schema unless explicitly
+ * opted out via `options.service: false`. Also generates for schemas that
+ * still use the legacy `options.api` block (unchanged from v3.22.x).
+ *
+ * Skipped automatically:
+ *  - kind != object (pivot, partial, enum, extend)
+ *  - options.service === false (explicit opt-out)
+ *  - schemas whose name matches a translation sidecar pattern
+ *    (`*Translation` auto-generated by the translation-model-generator)
+ *  - package-owned schemas (those get services in their owning package)
+ */
 export declare function generateServices(reader: SchemaReader, config: PhpConfig): GeneratedFile[];

package/ts-dist/php/service-generator.js

@@ -1,28 +1,108 @@
 /**
- * Generates base + editable service classes for schemas with `options.api`
- * or `options.service`.
+ * Generates base + editable service classes.
  *
  * Issue #57: Full BaseService codegen with translatable, softDelete, audit,
  * DB::transaction, eagerLoad/eagerCount, lookupFields, defaultSort.
+ *
+ * Issue #81 (v3.23.0): convention-over-configuration flip. Services are now
+ * generated by default for every project `kind: object` schema. Opt out with
+ * `options.service: false` (pivots, translation sidecars, audit logs).
+ * Property-level flags (`searchable`, `filterable`, `sortable`, `lookupable`,
+ * `defaultSort: asc|desc`) are the single source of truth — the legacy
+ * `options.service.{searchable,filterable,defaultSort,lookupFields,eagerLoad,
+ * eagerCount}` keys are deprecated and emit warnings at generate time.
  */
 import { toPascalCase, toSnakeCase } from './naming-helper.js';
 import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace } from './types.js';
 // ============================================================================
 // Public entry point
 // ============================================================================
-/** Generate service classes for all schemas with api or service config. */
+/**
+ * Generate service classes for every project object schema unless explicitly
+ * opted out via `options.service: false`. Also generates for schemas that
+ * still use the legacy `options.api` block (unchanged from v3.22.x).
+ *
+ * Skipped automatically:
+ *  - kind != object (pivot, partial, enum, extend)
+ *  - options.service === false (explicit opt-out)
+ *  - schemas whose name matches a translation sidecar pattern
+ *    (`*Translation` auto-generated by the translation-model-generator)
+ *  - package-owned schemas (those get services in their owning package)
+ */
 export function generateServices(reader, config) {
     const files = [];
-    // Merge schemas with api OR service options (union)
-    const candidates = {
-        ...reader.getSchemasWithApi(),
-        ...reader.getSchemasWithService(),
-    };
+    const candidates = {};
+    // Project-owned object schemas — the new default-enabled set (#81).
+    for (const [name, schema] of Object.entries(reader.getProjectObjectSchemas())) {
+        // #81 explicit opt-out: `service: false` on the schema
+        if (schema.options?.service === false) {
+            continue;
+        }
+        // Skip Astrotomic translation sidecars — they're auto-emitted as PHP
+        // translation models, not as full services. Heuristic by name suffix.
+        if (name.endsWith('Translation')) {
+            continue;
+        }
+        // Skip hidden schemas (options.hidden = true) — intentional internal types
+        if (schema.options?.hidden) {
+            continue;
+        }
+        candidates[name] = schema;
+    }
+    // Legacy `options.api` schemas — these are already in project set above
+    // (getSchemasWithApi is a subset of project schemas). We don't need a
+    // second pass for them unless someone sets `service: false` + `api: {}`
+    // on the same schema, in which case the explicit api opt-in wins.
+    for (const [name, schema] of Object.entries(reader.getSchemasWithApi())) {
+        if (!candidates[name]) {
+            candidates[name] = schema;
+        }
+    }
+    // Emit deprecation warnings once per schema for legacy service-block keys
+    // that now duplicate property-level metadata.
+    for (const [name, schema] of Object.entries(candidates)) {
+        warnLegacyServiceKeys(name, schema);
+    }
     for (const [name, schema] of Object.entries(candidates)) {
         files.push(...generateForSchema(name, schema, reader, config));
     }
     return files;
 }
+/**
+ * Print a deprecation warning (once per schema) for every legacy
+ * `options.service.*` key that duplicates property-level metadata.
+ * Each warning points at the property-level equivalent so the migration
+ * path is self-documenting.
+ */
+function warnLegacyServiceKeys(name, schema) {
+    const svc = schema.options?.service;
+    if (!svc || typeof svc !== 'object')
+        return;
+    const deprecations = [];
+    if (svc.searchable && svc.searchable.length > 0) {
+        deprecations.push({ key: 'searchable', replacement: "property-level `searchable: true` on each field" });
+    }
+    if (svc.filterable && svc.filterable.length > 0) {
+        deprecations.push({ key: 'filterable', replacement: "property-level `filterable: true` on each field" });
+    }
+    if (svc.defaultSort !== undefined) {
+        deprecations.push({ key: 'defaultSort', replacement: "property-level `defaultSort: asc|desc` on exactly one field" });
+    }
+    if (svc.lookupFields && svc.lookupFields.length > 0) {
+        deprecations.push({ key: 'lookupFields', replacement: "property-level `lookupable: true` on each field" });
+    }
+    if (svc.eagerLoad && svc.eagerLoad.length > 0) {
+        deprecations.push({ key: 'eagerLoad', replacement: "override `applyListEagerLoads()` / `applyFindByIdEagerLoads()` / `applyLookupEagerLoads()` in the editable service" });
+    }
+    if (svc.eagerCount && svc.eagerCount.length > 0) {
+        deprecations.push({ key: 'eagerCount', replacement: "override `applyListEagerLoads()` in the editable service and call `$query->withCount(...)`" });
+    }
+    for (const d of deprecations) {
+        console.warn(`[omnify-ts] ${name}.options.service.${d.key} is deprecated (#81) — ` +
+            `use ${d.replacement} instead. The legacy key still works for this ` +
+            `release but will be removed in a future major version.`);
+    }
+}
 function generateForSchema(name, schema, reader, config) {
     return [
         generateBaseService(name, schema, reader, config),
@@ -40,7 +120,11 @@ function resolveFieldLists(schema, reader, name) {
     const properties = schema.properties ?? {};
     const propertyOrder = reader.getPropertyOrder(name);
     const expandedProperties = reader.getExpandedProperties(name);
-    const svc = schema.options?.service;
+    // #81: options.service can now be `false` (explicit opt-out). Narrow to
+    // an object here so every downstream read works the same on both shapes;
+    // the opt-out is filtered before this function is reached.
+    const svcRaw = schema.options?.service;
+    const svc = (svcRaw && typeof svcRaw === 'object') ? svcRaw : {};
     const searchableFields = [];
     const filterableFields = [];
     const sortableFields = [];
@@ -173,6 +257,72 @@ function reconstructRelationTokens(items) {
         result.push(current);
     return result;
 }
+/**
+ * #81: resolve the lookup() projection from property-level `lookupable: true`
+ * flags. Returns snake_case column names. Always includes `id` at the head
+ * of the list because the caller always wants the primary key. Falls back
+ * to ['id', 'name', 'slug'] (filtered to actually-present columns) when no
+ * property is marked — matches the v3.22.x default for backward compat.
+ */
+function resolveLookupFields(schema) {
+    const properties = schema.properties ?? {};
+    const order = schema.propertyOrder ?? Object.keys(properties);
+    const explicit = [];
+    for (const propName of order) {
+        const prop = properties[propName];
+        if (!prop)
+            continue;
+        if (prop.lookupable) {
+            explicit.push(toSnakeCase(propName));
+        }
+    }
+    if (explicit.length > 0) {
+        // Always prefix with `id` so the caller can key the returned rows.
+        return explicit.includes('id') ? explicit : ['id', ...explicit];
+    }
+    // Default: id + name + slug if those columns exist on the schema
+    const defaults = ['id'];
+    if (properties['name'])
+        defaults.push('name');
+    if (properties['slug'])
+        defaults.push('slug');
+    return defaults;
+}
+/**
+ * #81: resolve the default sort from a property-level `defaultSort: asc|desc`
+ * flag. At most one property per schema should carry this; if multiple are
+ * present, the first one wins and a warning is printed. Falls back to the
+ * legacy `svc.defaultSort` string (deprecation warning fired elsewhere)
+ * then to `-created_at`.
+ */
+function resolveDefaultSort(schema, svc) {
+    const properties = schema.properties ?? {};
+    const order = schema.propertyOrder ?? Object.keys(properties);
+    let picked = null;
+    const collisions = [];
+    for (const propName of order) {
+        const prop = properties[propName];
+        if (!prop)
+            continue;
+        const dir = prop.defaultSort;
+        if (dir !== 'asc' && dir !== 'desc')
+            continue;
+        if (picked) {
+            collisions.push(propName);
+            continue;
+        }
+        picked = { colName: toSnakeCase(propName), direction: dir };
+    }
+    if (collisions.length > 0 && picked) {
+        console.warn(`[omnify-ts] ${schema.name}: multiple properties declare defaultSort ` +
+            `(${collisions.join(', ')}); using '${picked.colName}' and ignoring ` +
+            `the rest. Remove the extras to silence this warning.`);
+    }
+    if (picked) {
+        return picked.direction === 'desc' ? `-${picked.colName}` : picked.colName;
+    }
+    return svc.defaultSort ?? '-created_at';
+}
 /** Collect properties that have non-null defaults (for create() method). */
 function resolveDefaults(schema, reader, name) {
     const properties = schema.properties ?? {};
@@ -206,11 +356,23 @@ function generateBaseService(name, schema, reader, config) {
     const modelName = toPascalCase(name);
     const options = schema.options ?? {};
     const api = options.api ?? {};
-    const svc = options.service ?? {};
+    // #81: options.service can be `false` for explicit opt-out — narrow to
+    // a plain object so downstream reads of svc.* are always safe. The
+    // opt-out filter in generateServices() means we never reach this path
+    // for schemas that set `service: false`.
+    const svcRaw = options.service;
+    const svc = (svcRaw && typeof svcRaw === 'object') ? svcRaw : {};
     const hasSoftDelete = options.softDelete ?? false;
     const perPage = api.perPage ?? 25;
-    const hasApiConfig = options.api != null;
-    const lookup = api.lookup ?? (hasApiConfig ? true : (svc.lookupFields != null && svc.lookupFields.length > 0));
+    // #81: lookup fields come from property-level `lookupable: true`.
+    // Legacy `options.service.lookupFields` still honoured (deprecation warning
+    // fired earlier). Always emit lookup() — it's a free method on every
+    // generated service under the opt-out default.
+    const lookupFieldsFromProps = resolveLookupFields(schema);
+    const lookupFields = (svc.lookupFields && svc.lookupFields.length > 0)
+        ? [...svc.lookupFields]
+        : lookupFieldsFromProps;
+    const lookup = lookupFields.length > 0;
     // Audit detection — schema-level then global
     const schemaAudit = options.audit;
     const globalAudit = reader.getAuditConfig();
@@ -228,13 +390,14 @@ function generateBaseService(name, schema, reader, config) {
         fkColumn: `${modelSnake}_id`,
         translatableFields,
     };
-    // Eager load / count (#75.1: rejoin YAML-split `rel:col,col` tokens)
+    // Eager load / count — legacy YAML-declared (deprecated in #81, still
+    // honoured during the deprecation cycle). New code should override
+    // applyListEagerLoads() / applyFindByIdEagerLoads() / applyLookupEagerLoads()
+    // in the editable service.
     const eagerLoad = reconstructRelationTokens(svc.eagerLoad ?? []);
     const eagerCount = svc.eagerCount ?? [];
-    // Default sort
-    const defaultSort = svc.defaultSort ?? '-created_at';
-    // Lookup fields
-    const lookupFields = svc.lookupFields ?? ['id', 'name'];
+    // Default sort — #81: property-level `defaultSort: asc|desc` takes priority.
+    const defaultSort = resolveDefaultSort(schema, svc);
     // Field lists
     const { searchableFields, filterableFields, sortableFields } = resolveFieldLists(schema, reader, name);
     // Property defaults
@@ -293,6 +456,10 @@ function generateBaseService(name, schema, reader, config) {
         sections.push(buildSectionComment('Lookup'));
         sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort, translationCtx, reader, hasSoftDelete));
     }
+    // ── Eager Load Hooks (#81) ────────────────────────────────────────────────
+    sections.push('');
+    sections.push(buildSectionComment('Eager Load Hooks (#81)'));
+    sections.push(buildEagerLoadHooks());
     // ── Translatable helpers ──────────────────────────────────────────────────
     if (hasTranslatable) {
         sections.push('');
@@ -340,6 +507,63 @@ function buildSectionComment(title) {
     //  ${title}
     // =========================================================================`;
 }
+/**
+ * #81: empty protected hook methods that every read path calls after
+ * building its query. Consumers override these in the editable sibling
+ * service to apply per-method eager loads, keeping eager loading as a
+ * query-time concern (as every other ORM in the ecosystem does) instead
+ * of a schema-level one.
+ *
+ * The legacy `options.service.eagerLoad` / `eagerCount` YAML config is
+ * still honoured in v3.23.x — its emitted `->with(...)->withCount(...)`
+ * chain runs BEFORE the hook, so overrides compose additively. The YAML
+ * config will be removed in a future major release per the #81
+ * deprecation path.
+ */
+function buildEagerLoadHooks() {
+    return `
+    /**
+     * Override in the editable sibling service to eager-load relations
+     * on the list() query. Default: no-op. Legacy schema-level eagerLoad
+     * configuration still applies before this hook runs.
+     *
+     * @param  \\Illuminate\\Database\\Eloquent\\Builder  $query
+     */
+    protected function applyListEagerLoads($query): void
+    {
+        // Override in your editable service:
+        //   $query->with(['author', 'category'])->withCount(['comments']);
+    }
+
+    /**
+     * Override in the editable sibling service to eager-load relations on
+     * the findById() query. Default: no-op.
+     *
+     * @param  \\Illuminate\\Database\\Eloquent\\Builder  $query
+     */
+    protected function applyFindByIdEagerLoads($query): void
+    {
+        // Override in your editable service for detail-page eager loads:
+        //   $query->with([
+        //       'author:id,name',
+        //       'category',
+        //       'comments.author',
+        //   ]);
+    }
+
+    /**
+     * Override in the editable sibling service to eager-load relations on
+     * the lookup() query. Default: no-op. Most lookup endpoints should
+     * stay lean — eager loading defeats the point of a dropdown projection.
+     *
+     * @param  \\Illuminate\\Database\\Eloquent\\Builder  $query
+     */
+    protected function applyLookupEagerLoads($query): void
+    {
+        // Override only when the lookup result needs related data that
+        // can't come from the sidecar translation table.
+    }`;
+}
 // ============================================================================
 // #77 follow-up: strict @param array-shape + @example block derivation
 // ============================================================================
@@ -733,7 +957,7 @@ ${listExample}
     public function list(array $filters = []): LengthAwarePaginator
     {
         $query = $this->model::query()`);
-    // Eager load
+    // Eager load (legacy YAML-configured, deprecated #81)
     const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
     if (eagerChain) {
         lines.push(`${eagerChain};`);
@@ -742,6 +966,11 @@ ${listExample}
         // Close the query chain
         lines[lines.length - 1] += ';';
     }
+    // #81: user-overridable eager load hook. Runs after the legacy chain so
+    // subclass overrides compose additively on top of whatever YAML declared.
+    lines.push('');
+    lines.push('        // -- Eager loads via #81 hook (override applyListEagerLoads in sibling service) --');
+    lines.push('        $this->applyListEagerLoads($query);');
     // Filterable
     if (filterableFields.length > 0) {
         lines.push('');
@@ -888,7 +1117,9 @@ function buildSortSection(_sortableFields, defaultSort, allowedSortColumns, tx)
 // ── findById() ──────────────────────────────────────────────────────────────
 function buildFindByIdMethod(modelName, eagerLoad, eagerCount, hasSoftDelete) {
     const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
-    const chain = eagerChain ? `\n${eagerChain}\n            ` : '';
+    // Preserve a leading newline + the chain, but NO trailing whitespace so
+    // the semicolon lands cleanly in `$query = ...${chain};`
+    const chain = eagerChain ? `\n${eagerChain}` : '';
     if (!hasSoftDelete) {
         return `
     /**
@@ -902,7 +1133,10 @@ function buildFindByIdMethod(modelName, eagerLoad, eagerCount, hasSoftDelete) {
      */
     public function findById(string $id): ${modelName}
     {
-        return $this->model::query()${chain}->findOrFail($id);
+        $query = $this->model::query()${chain};
+        $this->applyFindByIdEagerLoads($query);
+
+        return $query->findOrFail($id);
     }`;
     }
     // #79: soft-deletable schemas accept an opt-in `$withTrashed` flag so admin
@@ -1248,6 +1482,10 @@ ${lookupExample}
             ->select([${selectFields}])
             ->orderBy('${sortCol}', '${sortDir}');
 
+        // #81: override applyLookupEagerLoads in sibling service to add any
+        // relations that the dropdown projection needs (keep it lean!).
+        $this->applyLookupEagerLoads($query);
+
 ${filterBlock}${softDeleteBlock}${limitBlock}
 
         // #76 followup (v3.21.2): use getAttributes() to bypass Astrotomic's

package/ts-dist/ts-service-generator.js

@@ -27,7 +27,12 @@ export function generateTsServices(schemas, options) {
 // Per-schema generator
 // ---------------------------------------------------------------------------
 function generateServiceFile(name, schema, options) {
-    const svc = schema.options?.service ?? {};
+    // #81: options.service can be `false` for explicit opt-out. Treat `false`
+    // the same as an empty service block for TS codegen purposes — the Go
+    // side already filtered this path when emitting the PHP base, but the
+    // TS side runs independently and needs its own narrowing.
+    const svcRaw = schema.options?.service;
+    const svc = (svcRaw && typeof svcRaw === 'object') ? svcRaw : {};
     const api = schema.options?.api;
     const hasSoftDelete = schema.options?.softDelete ?? false;
     const hasRestore = api?.restore ?? hasSoftDelete;

package/ts-dist/types.d.ts

@@ -117,13 +117,32 @@ export interface ApiOptions {
     readonly middleware?: readonly string[];
     readonly perPage?: number;
 }
-/** Service layer codegen options — controls BaseService generation. Issue #57. */
+/**
+ * Service layer codegen options — controls BaseService generation. Issue #57.
+ *
+ * #81 (v3.23.0): every field in this interface is DEPRECATED. Use the
+ * property-level flags instead (searchable / filterable / sortable /
+ * lookupable / defaultSort), which are the single source of truth. This
+ * interface is kept for backward compatibility and emits deprecation
+ * warnings from the generator when any legacy key is set.
+ *
+ * The only keys that will survive the deprecation cycle are legitimate
+ * service-level overrides that property-level can't express (pagination
+ * strategy, per_page default, etc.) — those will be added in a future
+ * release when the deprecations clear.
+ */
 export interface ServiceOptions {
+    /** @deprecated #81 — use property-level `searchable: true` instead */
     readonly searchable?: readonly string[];
+    /** @deprecated #81 — use property-level `filterable: true` instead */
     readonly filterable?: readonly string[];
+    /** @deprecated #81 — use property-level `defaultSort: 'asc'|'desc'` on exactly one field */
     readonly defaultSort?: string;
+    /** @deprecated #81 — override applyListEagerLoads/applyFindByIdEagerLoads/applyLookupEagerLoads in the editable service instead */
     readonly eagerLoad?: readonly string[];
+    /** @deprecated #81 — override applyListEagerLoads hook in the editable service instead */
     readonly eagerCount?: readonly string[];
+    /** @deprecated #81 — use property-level `lookupable: true` instead */
     readonly lookupFields?: readonly string[];
 }
 /** Schema options. */
@@ -142,8 +161,18 @@ export interface SchemaOptions {
         readonly updatedBy?: boolean;
         readonly deletedBy?: boolean;
     };
-    /** Service layer codegen options. Issue #57. */
-    readonly service?: ServiceOptions;
+    /**
+     * Service layer codegen options (issue #57).
+     *
+     * #81 (v3.23.0): accepts `false` as an explicit opt-out — every `kind:
+     * object` project schema gets a generated base service by default now.
+     * Set `service: false` on pivot tables / sidecars / audit logs that
+     * shouldn't have a service. Set to an object only for legitimate
+     * service-level overrides that property-level flags can't express
+     * (legacy property-duplication keys emit deprecation warnings at
+     * generate time).
+     */
+    readonly service?: ServiceOptions | false;
     /** Schema-level default ordering — generates a global Eloquent scope. Issue #40. */
     readonly defaultOrder?: readonly OrderByItem[];
 }
@@ -264,6 +293,21 @@ export interface PropertyDefinition {
     readonly searchable?: boolean;
     readonly filterable?: boolean;
     readonly sortable?: boolean;
+    /**
+     * #81: mark a property as part of the lookup() projection (id/label/slug
+     * shape for type-ahead / dropdown endpoints). When at least one property
+     * on a schema has `lookupable: true`, the generator uses that set instead
+     * of the legacy `options.service.lookupFields` array.
+     */
+    readonly lookupable?: boolean;
+    /**
+     * #81: declare this property as the schema's default sort column. At most
+     * one property per schema should set this. The value is the direction:
+     * `asc` emits `defaultSort: <col>`, `desc` emits `-<col>`. Legacy
+     * `options.service.defaultSort` is still honoured with a deprecation
+     * warning.
+     */
+    readonly defaultSort?: 'asc' | 'desc';
     readonly fields?: Record<string, FieldOverride>;
 }
 /** Single column ordering. Direction defaults to 'asc'. Issue #40. */