@metaobjectsdev/codegen-ts 0.5.0-rc.1

package/src/templates/entity-constants.ts

@@ -0,0 +1,248 @@
+// Entity-constants template — emits an `<Entity>` const with all the
+// metadata-derived strings consumers should use INSTEAD of magic strings.
+//
+// Shape (each non-$-prefixed key is a per-field object):
+//
+//   export const Subscriber = {
+//     $entity: "Subscriber",
+//     $table:  "subscribers",
+//     $path:   "/subscribers",
+//
+//     email: {
+//       name:        "email",
+//       label:       "Email Address",      // from @label on the view, falls back to humanized field name
+//       view:        "text",                // MetaView subtype
+//       htmlType:    "email",               // optional; only when it maps to a real HTML input type
+//       placeholder: "you@example.com",     // optional; only when @placeholder is set on the view
+//       helpText:    "We never share this.", // optional; only when @helpText is set
+//       rules: {                             // optional; derived from validator children
+//         required:  "Email is required",
+//         maxLength: { value: 255, message: "Must be 255 characters or fewer" },
+//         pattern:   { value: /.../, message: "Invalid email" },
+//       },
+//     },
+//     // ...
+//   } as const;
+//
+// Consumers spread `form.input.email` from useEntityForm and never touch
+// per-attribute access (placeholder, rules, etc.) by hand — the helper
+// picks them up from this object automatically.
+
+import { code, type Code } from "ts-poet";
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import {
+  VIEW_SUBTYPE_TEXT,
+  VIEW_SUBTYPE_TEXTAREA,
+  VIEW_SUBTYPE_NUMBER,
+  VIEW_SUBTYPE_CHECKBOX,
+  VIEW_SUBTYPE_DATE,
+  VIEW_SUBTYPE_PASSWORD,
+  VIEW_SUBTYPE_HIDDEN,
+  VIEW_SUBTYPE_DROPDOWN,
+  VIEW_SUBTYPE_RADIO,
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_ATTR_MIN,
+  VALIDATOR_ATTR_MAX,
+  VALIDATOR_ATTR_PATTERN,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_REQUIRED,
+} from "@metaobjectsdev/metadata";
+import { resolveTableName, pluralize, toSnakeCase } from "@metaobjectsdev/metadata";
+import { inferViewKind, currencyMetaFor, labelFor } from "./field-meta.js";
+
+/** Convert a camelCase or PascalCase field name to a human-friendly label. */
+function humanize(s: string): string {
+  return s
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}
+
+/**
+ * REST resource path for an entity. Pluralized + snake_cased + lowercased.
+ *   "Subscriber" → "/subscribers"
+ *   "WorkoutEvent" → "/workout_events"
+ */
+function resourcePath(entity: MetaData): string {
+  const overrideAttr = entity.ownAttr("routePath");
+  if (typeof overrideAttr === "string" && overrideAttr.length > 0) {
+    return overrideAttr.startsWith("/") ? overrideAttr : `/${overrideAttr}`;
+  }
+  return `/${pluralize(toSnakeCase(entity.name))}`;
+}
+
+/** Resolve the view subtype: explicit `view` child (own or inherited) wins, else inferred from field subType. */
+function resolveView(field: MetaField): { view: string; viewNode?: MetaData } {
+  const viewChild = field.views()[0];
+  if (viewChild) {
+    return { view: viewChild.subType, viewNode: viewChild };
+  }
+  return { view: inferViewKind(field) };
+}
+
+/**
+ * Map a MetaView subtype to a real HTML <input type=...> value. Returns
+ * undefined for views that don't map to <input> at all (textarea, dropdown,
+ * radio) — consumers render the right element type themselves.
+ */
+function htmlTypeFromView(view: string, override?: string): string | undefined {
+  if (typeof override === "string" && override.length > 0) return override;
+  switch (view) {
+    case VIEW_SUBTYPE_TEXT:
+      return "text";
+    case VIEW_SUBTYPE_NUMBER:
+      return "number";
+    case VIEW_SUBTYPE_DATE:
+      return "date";
+    case VIEW_SUBTYPE_PASSWORD:
+      return "password";
+    case VIEW_SUBTYPE_CHECKBOX:
+      return "checkbox";
+    case VIEW_SUBTYPE_HIDDEN:
+      return "hidden";
+    case VIEW_SUBTYPE_RADIO:
+      return "radio";
+    case "month":
+      return "month";
+    case "email":
+      return "email";
+    case VIEW_SUBTYPE_TEXTAREA:
+    case VIEW_SUBTYPE_DROPDOWN:
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Build RHF rules JSON-ish code from a field's validator children plus
+ * field-level attrs (`@required`, `@maxLength`). Returns the code string
+ * (e.g. `{ required: "X", maxLength: { value: 255, message: "..." } }`)
+ * or undefined when there are no rules to emit.
+ */
+function renderFieldRules(field: MetaField): string | undefined {
+  const ruleParts: string[] = [];
+
+  let hasRequired = false;
+  let hasMaxLength = false;
+
+  for (const child of field.validators()) {
+    if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) {
+      const msg = (child.ownAttr("message") as string | undefined) ?? `${humanize(field.name)} is required`;
+      ruleParts.push(`required: ${JSON.stringify(msg)}`);
+      hasRequired = true;
+    } else if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
+      const min = child.ownAttr(VALIDATOR_ATTR_MIN);
+      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      if (typeof min === "number") {
+        const msg = (child.ownAttr("minMessage") as string | undefined) ?? `Must be at least ${min} characters`;
+        ruleParts.push(`minLength: { value: ${min}, message: ${JSON.stringify(msg)} }`);
+      }
+      if (typeof max === "number") {
+        const msg = (child.ownAttr("maxMessage") as string | undefined) ?? `Must be ${max} characters or fewer`;
+        ruleParts.push(`maxLength: { value: ${max}, message: ${JSON.stringify(msg)} }`);
+        hasMaxLength = true;
+      }
+    } else if (child.subType === VALIDATOR_SUBTYPE_REGEX) {
+      const pattern = child.ownAttr(VALIDATOR_ATTR_PATTERN);
+      if (typeof pattern === "string") {
+        const msg = (child.ownAttr("message") as string | undefined) ?? "Invalid format";
+        // Emit as RegExp literal /.../ — `as const` preserves the value-ref.
+        // Forward-slash inside the pattern is escaped so the literal closes correctly.
+        const safe = pattern.replace(/\\/g, "\\\\").replace(/\//g, "\\/");
+        ruleParts.push(`pattern: { value: /${safe}/, message: ${JSON.stringify(msg)} }`);
+      }
+    }
+  }
+
+  // Field-level @required attr (if not already covered by validator).
+  if (!hasRequired && field.ownAttr(FIELD_ATTR_REQUIRED) === true) {
+    ruleParts.push(`required: ${JSON.stringify(`${humanize(field.name)} is required`)}`);
+  }
+
+  // Field-level @maxLength attr (if not already covered).
+  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  if (!hasMaxLength && typeof maxLenAttr === "number") {
+    ruleParts.push(
+      `maxLength: { value: ${maxLenAttr}, message: ${JSON.stringify(`Must be ${maxLenAttr} characters or fewer`)} }`,
+    );
+  }
+
+  if (ruleParts.length === 0) return undefined;
+  return `{ ${ruleParts.join(", ")} }`;
+}
+
+/** Build one nested field-object entry like `email: { name, label, ... },`. */
+function renderFieldEntry(field: MetaField): string {
+  const { view, viewNode } = resolveView(field);
+  const label = labelFor(field);
+  const placeholder = viewNode?.ownAttr("placeholder") as string | undefined;
+  const helpText = viewNode?.ownAttr("helpText") as string | undefined;
+  const htmlType = htmlTypeFromView(view, viewNode?.ownAttr("htmlType") as string | undefined);
+  const rules = renderFieldRules(field);
+
+  const entries: string[] = [
+    `name: ${JSON.stringify(field.name)}`,
+    `label: ${JSON.stringify(label)}`,
+    `view: ${JSON.stringify(view)}`,
+  ];
+  if (htmlType !== undefined) entries.push(`htmlType: ${JSON.stringify(htmlType)}`);
+  if (placeholder !== undefined) entries.push(`placeholder: ${JSON.stringify(placeholder)}`);
+  if (helpText !== undefined) entries.push(`helpText: ${JSON.stringify(helpText)}`);
+  if (rules !== undefined) entries.push(`rules: ${rules}`);
+
+  // Currency-specific keys: only emitted for currency-subtype fields.
+  const currencyMeta = currencyMetaFor(field);
+  if (currencyMeta !== null) {
+    entries.push(`currency: ${JSON.stringify(currencyMeta.currency)}`);
+    entries.push(`locale: ${JSON.stringify(currencyMeta.locale)}`);
+  }
+
+  return `  ${field.name}: {\n    ${entries.join(",\n    ")},\n  }`;
+}
+
+export function renderEntityConstants(obj: MetaObject, apiPrefix = ""): Code {
+  const entityName = obj.name;
+  const tableName = resolveTableName(obj);
+  const path = resourcePath(obj);
+
+  const fieldEntries: string[] = [];
+  // Use fields() so inherited fields (from extends:/super:) appear in constants.
+  for (const child of obj.fields()) {
+    fieldEntries.push(renderFieldEntry(child));
+  }
+
+  const body = [
+    `  $entity: ${JSON.stringify(entityName)}`,
+    `  $table: ${JSON.stringify(tableName)}`,
+    `  $path: ${JSON.stringify(path)}`,
+    `  $apiPrefix: ${JSON.stringify(apiPrefix)}`,
+    ...fieldEntries,
+  ].join(",\n");
+
+  return code`
+/**
+ * Metadata constants for ${entityName}.
+ *
+ * Use these instead of magic strings so TS catches typos and refactors stay
+ * coherent. Each non-dollar-prefixed key is a per-field object carrying
+ * name, label, view, optional htmlType/placeholder/helpText, and the
+ * RHF-shaped validation rules derived from the field's validator children.
+ *
+ * Typical usage with the metaobjects React form helper:
+ *
+ *   import { useEntityForm } from '@metaobjectsdev/react';
+ *   const form = useEntityForm(${entityName}, ${entityName}InsertSchema);
+ *   <input {...form.input.${
+    fieldEntries[0]?.match(/^\s*(\w+):/)?.[1] ?? "fieldName"
+  }} />
+ */
+export const ${entityName} = {
+${body},
+} as const;
+`;
+}

package/src/templates/entity-file.ts

@@ -0,0 +1,51 @@
+// Entity file composer — combines drizzle-schema, inferred-types, and zod-validators
+// into one file with the @generated header. ts-poet deduplicates imports.
+//
+// Dispatch:
+//   isProjection(entity)  → renderProjectionDecl (read-only: view declaration + Zod + filter sections)
+//   vanilla / write-through entity → Drizzle table path
+
+import { joinCode, type Code } from "ts-poet";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { RenderContext } from "../render-context.js";
+import { renderDrizzleSchema } from "./drizzle-schema.js";
+import { renderInferredTypes } from "./inferred-types.js";
+import { renderZodValidators } from "./zod-validators.js";
+import { renderEntityConstants } from "./entity-constants.js";
+import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
+import { renderFilterType } from "./filter-type.js";
+import { GENERATED_HEADER } from "../constants.js";
+import { isProjection } from "../projection/projection-detector.js";
+import { renderProjectionDecl } from "./projection-decl.js";
+
+export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string {
+  // --- Projection path (read-only: view-backed entity with no table source) ---
+  if (isProjection(entity)) {
+    return renderProjectionDecl(entity, ctx.loadedRoot, {
+      columnNamingStrategy: ctx.columnNamingStrategy,
+      dialect: ctx.dialect,
+      apiPrefix: ctx.apiPrefix,
+    });
+  }
+
+  // --- Vanilla / write-through entity path ---
+  const sections: Code[] = [
+    renderDrizzleSchema(entity, ctx),
+    renderInferredTypes(entity),
+    renderZodValidators(entity),
+    renderEntityConstants(entity, ctx.apiPrefix),
+    renderFilterAllowlist(entity),
+    renderSortAllowlist(entity),
+    renderFilterType(entity),
+  ];
+
+  // Render ts-poet body first (ts-poet hoists imp()-tracked imports to the top),
+  // then prepend the @generated header so it lands at line 1 — convention for
+  // generated files and what most tooling (overwrite-policy, IDEs) expects.
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entity.name} (${entity.fqn()})\n` +
+    `// Customize via ${entity.name}.extra.ts in this directory.\n`;
+  return header + body;
+}

package/src/templates/field-meta.ts

@@ -0,0 +1,150 @@
+// Shared field-level metadata helpers — consumed by entity-constants.ts,
+// projection-decl.ts, and any future generator that needs per-field inference.
+//
+// All helpers take a MetaField node.
+
+import { MetaField } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_CURRENCY,
+  VIEW_SUBTYPE_TEXT,
+  VIEW_SUBTYPE_DATE,
+  VIEW_SUBTYPE_NUMBER,
+  VIEW_SUBTYPE_CHECKBOX,
+  VIEW_SUBTYPE_CURRENCY,
+  FIELD_ATTR_CURRENCY,
+  FIELD_ATTR_CURRENCY_DEFAULT,
+  VIEW_CURRENCY_ATTR_LOCALE,
+  VIEW_CURRENCY_ATTR_LOCALE_DEFAULT,
+} from "@metaobjectsdev/metadata";
+
+// ---------------------------------------------------------------------------
+// inferViewKind
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the cell-renderer key (view kind) for a field.
+ * Explicit view child wins; field subType determines default.
+ */
+export function inferViewKind(field: MetaField): string {
+  // Explicit view (own or inherited via extends) has highest priority.
+  const viewChild = field.views()[0];
+  if (viewChild) return viewChild.subType;
+  // Field subtype → default view.
+  return defaultViewForSubType(field.subType);
+}
+
+function defaultViewForSubType(subType: string): string {
+  switch (subType) {
+    case FIELD_SUBTYPE_BOOLEAN:
+      return VIEW_SUBTYPE_CHECKBOX;
+    case FIELD_SUBTYPE_INT:
+    case FIELD_SUBTYPE_LONG:
+    case FIELD_SUBTYPE_SHORT:
+    case FIELD_SUBTYPE_BYTE:
+    case FIELD_SUBTYPE_DOUBLE:
+    case FIELD_SUBTYPE_FLOAT:
+    case FIELD_SUBTYPE_DECIMAL:
+      return VIEW_SUBTYPE_NUMBER;
+    case FIELD_SUBTYPE_DATE:
+    case FIELD_SUBTYPE_TIME:
+    case FIELD_SUBTYPE_TIMESTAMP:
+      return VIEW_SUBTYPE_DATE;
+    case FIELD_SUBTYPE_CURRENCY:
+      return VIEW_SUBTYPE_CURRENCY;
+    default:
+      return VIEW_SUBTYPE_TEXT;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// zodTypeFor
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Zod validator expression for a field's storage type.
+ */
+export function zodTypeFor(field: MetaField): string {
+  switch (field.subType) {
+    case FIELD_SUBTYPE_STRING:
+      return "z.string()";
+    case FIELD_SUBTYPE_BOOLEAN:
+      return "z.boolean()";
+    case FIELD_SUBTYPE_DATE:
+    case FIELD_SUBTYPE_TIME:
+    case FIELD_SUBTYPE_TIMESTAMP:
+      // Returned as ISO strings from SQLite/Postgres drivers.
+      return "z.string()";
+    case FIELD_SUBTYPE_INT:
+    case FIELD_SUBTYPE_LONG:
+    case FIELD_SUBTYPE_SHORT:
+    case FIELD_SUBTYPE_BYTE:
+    case FIELD_SUBTYPE_CURRENCY:
+      return "z.number().int()";
+    case FIELD_SUBTYPE_DOUBLE:
+    case FIELD_SUBTYPE_FLOAT:
+    case FIELD_SUBTYPE_DECIMAL:
+      return "z.number()";
+    default:
+      return "z.unknown()";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// currencyMetaFor
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve currency code + locale for a currency-subtype field.
+ * Returns null for non-currency fields.
+ */
+export function currencyMetaFor(field: MetaField): { currency: string; locale: string } | null {
+  if (field.subType !== FIELD_SUBTYPE_CURRENCY) return null;
+  const currency =
+    (field.ownAttr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
+  const viewChild = field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
+  const locale =
+    (viewChild?.ownAttr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??
+    VIEW_CURRENCY_ATTR_LOCALE_DEFAULT;
+  return { currency, locale };
+}
+
+// ---------------------------------------------------------------------------
+// labelFor
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the human-readable label for a field.
+ * Uses @label attr on a view child if present; otherwise humanizes the field name.
+ */
+export function labelFor(field: MetaField): string {
+  for (const child of field.views()) {
+    const label = child.ownAttr("label");
+    if (typeof label === "string" && label.length > 0) return label;
+  }
+  return humanize(field.name);
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/** Convert a camelCase or PascalCase field name to a human-friendly label. */
+function humanize(s: string): string {
+  return s
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}

package/src/templates/filter-allowlist.ts

@@ -0,0 +1,104 @@
+import { code, type Code } from "ts-poet";
+import { MetaField, MetaObject } from "@metaobjectsdev/metadata";
+import {
+  FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  opsForSubType,
+} from "@metaobjectsdev/metadata";
+import { sortableFields } from "./filter-shared.js";
+
+const NUMBER_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+]);
+
+const DATETIME_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+]);
+
+/** Maps a field subtype to the FilterSubType category used in generated FilterAllowlist. */
+function filterSubTypeFor(fieldSubType: string): "string" | "number" | "boolean" | "datetime" {
+  if (fieldSubType === FIELD_SUBTYPE_BOOLEAN) return "boolean";
+  if (NUMBER_SUBTYPES.has(fieldSubType)) return "number";
+  if (DATETIME_SUBTYPES.has(fieldSubType)) return "datetime";
+  return "string";
+}
+
+function filterableFields(entity: MetaObject): MetaField[] {
+  // fields() returns effective fields, so inherited fields (from extends:/super:) are included in allowlists.
+  return entity.fields().filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true);
+}
+
+export function renderFilterAllowlist(entity: MetaObject): Code {
+  const fields = filterableFields(entity);
+  if (fields.length === 0) {
+    return code`
+import type { FilterAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";
+
+export const ${entity.name}FilterAllowlist = {} as const satisfies FilterAllowlist;
+`;
+  }
+  const rows = fields
+    .map((f) => {
+      const ops = opsForSubType(f.subType).map((o) => JSON.stringify(o)).join(", ");
+      const sub = filterSubTypeFor(f.subType);
+      return `  ${f.name}: { ops: [${ops}] as const, subType: ${JSON.stringify(sub)} as const, leadingWildcard: false }`;
+    })
+    .join(",\n");
+  return code`
+import type { FilterAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";
+
+export const ${entity.name}FilterAllowlist = {
+${rows}
+} as const satisfies FilterAllowlist;
+`;
+}
+
+export function renderSortAllowlist(entity: MetaObject): Code {
+  // Sortable = explicit @sortable === true, OR (no @sortable AND @filterable === true).
+  // @sortable: false explicitly opts out.
+  // Uses shared isSortableField predicate — must stay in sync with renderFilterType.
+  const sortable = sortableFields(entity);
+  if (sortable.length === 0) {
+    return code`
+import type { SortAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";
+
+export const ${entity.name}SortAllowlist = {} as const satisfies SortAllowlist;
+`;
+  }
+  const rows = sortable
+    .map((f) => {
+      const defaultOrder = f.ownAttr(FIELD_ATTR_SORTABLE_DEFAULT_ORDER) as string | undefined;
+      const rule =
+        defaultOrder === "asc" || defaultOrder === "desc"
+          ? `{ defaultOrder: ${JSON.stringify(defaultOrder)} as const }`
+          : `{}`;
+      return `  ${f.name}: ${rule}`;
+    })
+    .join(",\n");
+  return code`
+import type { SortAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";
+
+export const ${entity.name}SortAllowlist = {
+${rows}
+} as const satisfies SortAllowlist;
+`;
+}

package/src/templates/filter-shared.ts

@@ -0,0 +1,30 @@
+// Shared predicate for "is this field sortable?" — used by both filter-allowlist.ts
+// (SortAllowlist generation) and filter-type.ts (sort union generation).
+// Both must agree on which fields are sortable; keeping them in sync via this shared
+// helper prevents client/server mismatches.
+
+import { MetaField, MetaObject } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_FILTERABLE, FIELD_ATTR_SORTABLE } from "@metaobjectsdev/metadata";
+
+/**
+ * Returns true if the given field should be included in sort operations.
+ *
+ * Rules (in priority order):
+ *   1. @sortable: true  → always sortable (even without @filterable)
+ *   2. @sortable: false → never sortable (overrides @filterable)
+ *   3. no @sortable     → sortable iff @filterable === true
+ */
+export function isSortableField(field: MetaField): boolean {
+  const sortableAttr = field.ownAttr(FIELD_ATTR_SORTABLE);
+  if (sortableAttr === true) return true;
+  if (sortableAttr === false) return false;
+  return field.ownAttr(FIELD_ATTR_FILTERABLE) === true;
+}
+
+/**
+ * Returns all sortable field children of the given entity.
+ */
+export function sortableFields(entity: MetaObject): MetaField[] {
+  // fields() returns effective fields, so inherited fields (from extends:/super:) are included in sort ops.
+  return entity.fields().filter(isSortableField);
+}

package/src/templates/filter-type.ts

@@ -0,0 +1,93 @@
+// Filter type template — emits <Entity>Filter type with subtype-gated operators.
+// String fields get eq/ne/in/like; numbers get eq/ne/gt/gte/lt/lte/in; booleans get eq/isNull only;
+// datetimes get eq/ne/gt/gte/lt/lte/in.
+
+import { code, type Code } from "ts-poet";
+import { MetaField, MetaObject } from "@metaobjectsdev/metadata";
+import {
+  FIELD_ATTR_FILTERABLE,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  opsForSubType,
+} from "@metaobjectsdev/metadata";
+import { isSortableField } from "./filter-shared.js";
+
+const NUMBER_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+]);
+
+/** Maps a field subtype to its TS value type name for operator union codegen. */
+function tsNameFor(fieldSubType: string): string {
+  if (fieldSubType === FIELD_SUBTYPE_BOOLEAN) return "boolean";
+  if (NUMBER_SUBTYPES.has(fieldSubType)) return "number";
+  return "string";
+}
+
+function renderFieldUnion(field: MetaField): string {
+  const ops = opsForSubType(field.subType);
+  const tsName = tsNameFor(field.subType);
+  const opEntries = ops.map((op) => {
+    if (op === "in") return `in?: ${tsName}[]`;
+    if (op === "isNull") return `isNull?: boolean`;
+    if (op === "like") return `like?: string`;
+    return `${op}?: ${tsName}`;
+  });
+  return `${tsName} | { ${opEntries.join("; ")} }`;
+}
+
+export function renderFilterType(entity: MetaObject): Code {
+  // fields() returns effective fields, so inherited fields (from extends:/super:) are included in filter types.
+  const allFields = entity.fields();
+  const filterableFieldsList = allFields.filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true);
+  // Sort union uses isSortableField — same predicate as renderSortAllowlist to prevent
+  // client/server mismatches (@filterable: true + @sortable: false must be excluded from both).
+  const sortFieldNames = allFields.filter(isSortableField).map((f) => `"${f.name}"`);
+
+  const fieldLines: string[] = [];
+  for (const f of filterableFieldsList) {
+    fieldLines.push(`  ${f.name}?: ${renderFieldUnion(f)};`);
+  }
+
+  if (fieldLines.length === 0 && sortFieldNames.length === 0) {
+    return code`
+export type ${entity.name}Filter = {
+  limit?: number;
+  offset?: number;
+  sort?: string;
+  or?: ${entity.name}Filter[];
+  and?: ${entity.name}Filter[];
+};
+`;
+  }
+
+  const sortType =
+    sortFieldNames.length === 0
+      ? `string`
+      : (() => {
+          const sortUnion = sortFieldNames.join(" | ");
+          return `\`\${${sortUnion}}:\${"asc" | "desc"}\` | ${sortUnion}`;
+        })();
+
+  return code`
+export type ${entity.name}Filter = {
+  limit?: number;
+  offset?: number;
+  sort?: ${sortType};
+${fieldLines.join("\n")}
+  or?: ${entity.name}Filter[];
+  and?: ${entity.name}Filter[];
+};
+`;
+}