@metaobjectsdev/metadata 0.5.0-rc.1

package/src/core/attr/meta-attr-properties.ts

@@ -0,0 +1,26 @@
+// PropertiesAttr — attr subtype `properties`. Object-shaped value (a string
+// bag / arbitrary JSON object). No desugar (identity); object validation.
+
+import { MetaAttr, type ValueError, runtimeTypeName } from "./meta-attr.js";
+import { type AttrValue } from "../../shared/meta-data.js";
+import { DATA_TYPE_OBJECT, type DataType } from "../../data-type.js";
+import { registerAttrClass } from "../../attr-class-map.js";
+import { ATTR_SUBTYPE_PROPERTIES } from "./attr-constants.js";
+
+export class PropertiesAttr extends MetaAttr {
+  override get dataType(): DataType {
+    return DATA_TYPE_OBJECT;
+  }
+
+  override coerce(raw: unknown): AttrValue {
+    return raw as AttrValue;
+  }
+
+  override validateValue(value: AttrValue): ValueError[] {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? []
+      : [{ message: `attribute '@${this.name}' must be of type 'properties' but got ${runtimeTypeName(value)}` }];
+  }
+}
+
+registerAttrClass(ATTR_SUBTYPE_PROPERTIES, PropertiesAttr);

package/src/core/attr/meta-attr-stringarray.ts

@@ -0,0 +1,31 @@
+// StringArrayAttr — attr subtype `stringarray`. A bare string is the degenerate
+// one-element authoring form (`"@fields": "id"`); coerce wraps it into a
+// one-element array so the loaded tree always holds a real string[]. Moved here
+// from parser-core.ts `normalizeStringArrayAttr`.
+
+import { MetaAttr, type ValueError, runtimeTypeName } from "./meta-attr.js";
+import { type AttrValue } from "../../shared/meta-data.js";
+import { DATA_TYPE_STRING, type DataType } from "../../data-type.js";
+import { registerAttrClass } from "../../attr-class-map.js";
+import { ATTR_SUBTYPE_STRINGARRAY } from "./attr-constants.js";
+
+export class StringArrayAttr extends MetaAttr {
+  override get dataType(): DataType {
+    return DATA_TYPE_STRING;
+  }
+
+  override coerce(raw: unknown): AttrValue {
+    if (Array.isArray(raw)) return raw.map((el) => String(el));
+    if (typeof raw === "string") return [raw];
+    // Non-string scalar (number/boolean) → leave as-is so validateValue flags it.
+    return raw as AttrValue;
+  }
+
+  override validateValue(value: AttrValue): ValueError[] {
+    return Array.isArray(value) && value.every((el) => typeof el === "string")
+      ? []
+      : [{ message: `attribute '@${this.name}' must be a string[] but got ${runtimeTypeName(value)}` }];
+  }
+}
+
+registerAttrClass(ATTR_SUBTYPE_STRINGARRAY, StringArrayAttr);

package/src/core/attr/meta-attr.ts

@@ -0,0 +1,125 @@
+// MetaAttr — concrete node class for type=attr nodes.
+//
+// Every attribute in the loaded model is a MetaAttr instance (inline @-syntax is
+// parse-time sugar; see parser-core.ts). The base class owns value behavior —
+// dataType / coerce / validateValue / desugar — resolved by this.subType.
+// Subclasses (StringArrayAttr, FilterAttr, PropertiesAttr) override only what
+// differs. Adding a new value-shaped attr subtype is one subclass + one
+// registration line in core-types.ts (ATTR_CLASS_MAP) — zero central edits.
+
+import { MetaData, type AttrValue } from "../../shared/meta-data.js";
+import {
+  type DataType,
+  type DataTypeAware,
+  DATA_TYPE_STRING,
+  DATA_TYPE_INT,
+  DATA_TYPE_LONG,
+  DATA_TYPE_DOUBLE,
+  DATA_TYPE_BOOLEAN,
+} from "../../data-type.js";
+import { convertToDataType, toAttrValue } from "../../data-converter.js";
+import { registerFallbackAttrClass } from "../../attr-class-map.js";
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+import { RESERVED_KEY_VALUE } from "../../shared/structural.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_CLASS,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_LONG,
+  ATTR_SUBTYPE_DOUBLE,
+  ATTR_SUBTYPE_BOOLEAN,
+} from "./attr-constants.js";
+
+/** A value-level validation finding, surfaced by the attr-schema pass. */
+export interface ValueError {
+  message: string;
+}
+
+/** Base-subtype → DataType. Each MetaAttr subclass owns its own DataType: the
+ *  base covers the scalar/string subtypes; object/array subtypes override
+ *  `get dataType()`. This replaces the central ATTR_DATA_TYPE map. */
+const BASE_ATTR_DATA_TYPE: Readonly<Record<string, DataType>> = {
+  [SUBTYPE_BASE]: DATA_TYPE_STRING,
+  [ATTR_SUBTYPE_STRING]: DATA_TYPE_STRING,
+  [ATTR_SUBTYPE_CLASS]: DATA_TYPE_STRING,
+  [ATTR_SUBTYPE_INT]: DATA_TYPE_INT,
+  [ATTR_SUBTYPE_LONG]: DATA_TYPE_LONG,
+  [ATTR_SUBTYPE_DOUBLE]: DATA_TYPE_DOUBLE,
+  [ATTR_SUBTYPE_BOOLEAN]: DATA_TYPE_BOOLEAN,
+};
+
+export class MetaAttr extends MetaData implements DataTypeAware {
+  /** This attribute's coerced value (stored on the instance under RESERVED_KEY_VALUE). */
+  get value(): AttrValue | undefined {
+    return this.ownAttr(RESERVED_KEY_VALUE);
+  }
+
+  /** The coarse value-type classification for this attribute's subtype. */
+  get dataType(): DataType {
+    return BASE_ATTR_DATA_TYPE[this.subType] ?? DATA_TYPE_STRING;
+  }
+
+  /**
+   * Coerce a raw parsed value toward this attr's value shape. The base handles
+   * the scalar subtypes (string / class / int / long / double / boolean) by
+   * delegating to convertToDataType. Subclasses override for array/object shapes.
+   *
+   * SUBTYPE_BASE is the polymorphic/unconstrained marker (e.g. an `attr.base`
+   * child node, or an untyped `@default`): the value is stored type-preserved,
+   * never stringified — mirroring validateValue, which accepts any type for base.
+   */
+  coerce(raw: unknown): AttrValue {
+    if (this.subType === SUBTYPE_BASE) {
+      return toAttrValue(raw);
+    }
+    return convertToDataType(this.dataType, raw);
+  }
+
+  /**
+   * Desugar a coerced value to its canonical stored form. Default identity;
+   * FilterAttr overrides to normalize `{ field: value }` → `{ field: { op: value } }`.
+   */
+  desugar(value: AttrValue): AttrValue {
+    return value;
+  }
+
+  /**
+   * Validate a stored value against this attr's value shape. Returns [] when
+   * valid. The base checks the scalar/string subtypes; subclasses override for
+   * array/object shapes. Replaces the central valueMatchesType + subtype-sets.
+   */
+  validateValue(value: AttrValue): ValueError[] {
+    const dt = this.dataType;
+    if (dt === DATA_TYPE_STRING) {
+      return typeof value === "string" ? [] : [this._typeError("string", value)];
+    }
+    if (dt === DATA_TYPE_INT || dt === DATA_TYPE_LONG || dt === DATA_TYPE_DOUBLE) {
+      return typeof value === "number" ? [] : [this._typeError("number", value)];
+    }
+    if (dt === DATA_TYPE_BOOLEAN) {
+      return typeof value === "boolean" ? [] : [this._typeError("boolean", value)];
+    }
+    // SUBTYPE_BASE / unconstrained — accept anything.
+    return [];
+  }
+
+  protected _typeError(_expected: string, value: AttrValue): ValueError {
+    return {
+      message:
+        `attribute '@${this.name}' must be of type '${this.subType}' ` +
+        `but got ${runtimeTypeName(value)}`,
+    };
+  }
+}
+
+/** Human-readable runtime type of an attr value, for error messages. */
+export function runtimeTypeName(value: AttrValue): string {
+  if (Array.isArray(value)) return "array";
+  if (value !== null && typeof value === "object") return "object";
+  return typeof value;
+}
+
+// Register the base MetaAttr as the fallback for unmapped (scalar/string) attr
+// subtypes. Subclasses register their own subtype in their module (see
+// meta-attr-stringarray / -filter / -properties).
+registerFallbackAttrClass(MetaAttr);

package/src/core/export-json.ts

@@ -0,0 +1,66 @@
+// Convenience export API — load a metadata directory and emit one flattened
+// canonical-JSON document.
+//
+// This module wires Loader + canonicalSerialize into a single call so
+// consumers (e.g. a React app's build step, the upcoming `meta export` CLI
+// command) can go from "a directory of meta.*.json files" to "one JSON
+// payload" without having to orchestrate the two steps manually.
+//
+// Error semantics (match Loader's own conventions):
+//   - Content errors (parse/validation failures) are collected in errors[] and
+//     returned in the result — they do NOT throw. `json` is still produced from
+//     whatever tree the Loader returned (Loader always returns a valid MetaData).
+//   - I/O failures (missing/unreadable directory) are caught by
+//     `loadFromDirectory` and returned in its `errors[]`; `loadAndExportJson`
+//     surfaces them unchanged in `ExportResult.errors`. It does not throw for
+//     directory or metadata problems.
+
+import { FileMetaDataLoader } from "./file-meta-data-loader.js";
+import type { LoadOptions } from "../loader/meta-data-loader.js";
+import { canonicalSerialize } from "../serializer-json.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ExportResult {
+  /** The single flattened canonical-JSON document of the entire loaded metadata model. */
+  json: string;
+  /**
+   * Parse/validation errors collected during load.
+   * Non-empty → `json` may be partial or empty; the caller decides whether to use it.
+   */
+  errors: Error[];
+  /** Non-fatal warnings collected during load. */
+  warnings: string[];
+}
+
+/**
+ * Load all metadata under `dir` and export the entire model as one flattened
+ * canonical-JSON document.
+ *
+ * Internally constructs a fresh `FileMetaDataLoader` (using the default registry
+ * composed via `composeRegistry(coreProviders)`), calls `loadDirectory`, then serializes the
+ * resulting tree with `canonicalSerialize`.
+ *
+ * @param dir  Absolute or relative path to the directory containing `meta.*.json` files.
+ * @param opts Optional loader options forwarded to the `FileMetaDataLoader` constructor
+ *             (registry, freeze, strict). The `exclude` glob list can be
+ *             supplied as `opts.exclude` — see `FileMetaDataLoader.loadDirectory`.
+ */
+export async function loadAndExportJson(
+  dir: string,
+  opts?: LoadOptions & { exclude?: string[] },
+): Promise<ExportResult> {
+  const { exclude, ...loaderOpts } = opts ?? {};
+  const loader = new FileMetaDataLoader(loaderOpts);
+  // Only pass the exclude option when defined, to satisfy exactOptionalPropertyTypes.
+  const dirOpts = exclude !== undefined ? { exclude } : undefined;
+  const result = await loader.loadDirectory(dir, dirOpts);
+  const json = canonicalSerialize(result.root);
+  return {
+    json,
+    errors: result.errors,
+    warnings: result.warnings,
+  };
+}

package/src/core/field/field-constants.ts

@@ -0,0 +1,79 @@
+// Field concern constants — subtypes, field-level attr keys, and currency attrs.
+
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+
+// ---------------------------------------------------------------------------
+// Field subtypes (15)
+// ---------------------------------------------------------------------------
+
+export const FIELD_SUBTYPE_STRING = "string";
+export const FIELD_SUBTYPE_INT = "int";
+export const FIELD_SUBTYPE_SHORT = "short";
+export const FIELD_SUBTYPE_BYTE = "byte";
+export const FIELD_SUBTYPE_LONG = "long";
+export const FIELD_SUBTYPE_DOUBLE = "double";
+export const FIELD_SUBTYPE_FLOAT = "float";
+export const FIELD_SUBTYPE_DECIMAL = "decimal";
+export const FIELD_SUBTYPE_BOOLEAN = "boolean";
+export const FIELD_SUBTYPE_DATE = "date";
+export const FIELD_SUBTYPE_TIME = "time";
+export const FIELD_SUBTYPE_TIMESTAMP = "timestamp";
+export const FIELD_SUBTYPE_OBJECT = "object";
+export const FIELD_SUBTYPE_CLASS = "class";
+export const FIELD_SUBTYPE_CURRENCY = "currency";
+
+export const FIELD_SUBTYPES = [
+  SUBTYPE_BASE,
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_CURRENCY,
+] as const;
+export type FieldSubType = (typeof FIELD_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Field-level attrs (used by codegen-ts column mapper)
+// ---------------------------------------------------------------------------
+
+export const FIELD_ATTR_REQUIRED = "required";
+export const FIELD_ATTR_UNIQUE = "unique";
+export const FIELD_ATTR_DEFAULT = "default";
+export const FIELD_ATTR_MAX_LENGTH = "maxLength";
+export const FIELD_ATTR_PRECISION = "precision";
+export const FIELD_ATTR_SCALE = "scale";
+export const FIELD_ATTR_FILTERABLE = "filterable";
+export const FIELD_ATTR_SORTABLE = "sortable";
+export const FIELD_ATTR_SORTABLE_DEFAULT_ORDER = "sortableDefaultOrder";
+
+/** Auto-set semantics on a timestamp field. Values: "onCreate" | "onUpdate". */
+export const FIELD_ATTR_AUTO_SET = "autoSet";
+
+/** Name (or FQN) of the target object an object-typed field nests. Same wire
+ *  spelling as the relationship `@objectRef` — Java's single ATTR_OBJECT_REF. */
+export const FIELD_ATTR_OBJECT_REF = "objectRef";
+
+export const AUTO_SET_ON_CREATE = "onCreate";
+export const AUTO_SET_ON_UPDATE = "onUpdate";
+
+export const AUTO_SET_VALUES = [AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE] as const;
+export type AutoSetValue = (typeof AUTO_SET_VALUES)[number];
+
+// ---------------------------------------------------------------------------
+// Currency attrs (on currency-subtype fields)
+// ---------------------------------------------------------------------------
+
+/** ISO 4217 currency code on a currency-subtype field. Defaults to "USD" when omitted. */
+export const FIELD_ATTR_CURRENCY = "currency";
+/** Default ISO 4217 currency code when @currency is omitted on a currency field. */
+export const FIELD_ATTR_CURRENCY_DEFAULT = "USD";

package/src/core/field/field-schema.ts

@@ -0,0 +1,121 @@
+// Field attribute schemas — attrs common to every field subtype, plus the
+// @currency attr specific to field.currency. Consumed by registerCoreTypes().
+
+import type { AttrSchema } from "../../registry.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_BOOLEAN,
+} from "../attr/attr-constants.js";
+import { SORT_ORDER_VALUES } from "../query/query-constants.js";
+import {
+  FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_UNIQUE,
+  FIELD_ATTR_DEFAULT,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_SCALE,
+  FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_SORTABLE,
+  FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
+  FIELD_ATTR_CURRENCY,
+  FIELD_ATTR_CURRENCY_DEFAULT,
+  FIELD_ATTR_AUTO_SET,
+  AUTO_SET_VALUES,
+} from "./field-constants.js";
+
+/** Attrs common to every field subtype (codegen-ts column mapper + Project D filter/sort). */
+export const commonFieldAttrs: AttrSchema[] = [
+  {
+    name: FIELD_ATTR_OBJECT_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description:
+      "Name (or FQN) of the target object an object-typed field nests — drives nested-object (de)serialization.",
+  },
+  {
+    name: FIELD_ATTR_REQUIRED,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "When true, the field is NOT NULL. Equivalent to attaching a validator.required child.",
+  },
+  {
+    name: FIELD_ATTR_UNIQUE,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description: "When true, the field gets a column-level UNIQUE constraint.",
+  },
+  {
+    name: FIELD_ATTR_DEFAULT,
+    // @default is polymorphic: its value type follows the OWNING field's
+    // subtype — a boolean field defaults to a boolean, an int field to a
+    // number, a string field to a string. No single fixed valueType can
+    // capture that, so valueType is intentionally omitted (declared-but-untyped).
+    // The parser stores the raw JSON value type-preserved (no coercion).
+    // Typed conversion happens at consumption time via MetaField.defaultValue(),
+    // which applies the field's own DataType — Java parity with
+    // MetaField.getDefaultValue() / DataConverter.toTypeSafe(getDataType(), o).
+    required: false,
+    description:
+      "Default value applied to the column when no value is supplied. Its type follows the field's own subtype (string / boolean / number / ...). Converted at consumption time via MetaField.defaultValue().",
+  },
+  {
+    name: FIELD_ATTR_MAX_LENGTH,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Maximum character length for string-typed fields (drives VARCHAR(n)).",
+  },
+  {
+    name: FIELD_ATTR_PRECISION,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Total number of significant digits for decimal-typed fields.",
+  },
+  {
+    name: FIELD_ATTR_SCALE,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Number of digits to the right of the decimal point for decimal-typed fields.",
+  },
+  {
+    name: FIELD_ATTR_FILTERABLE,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "When true, the field is exposed in generated CRUD filter allowlists (Project D filter layer).",
+  },
+  {
+    name: FIELD_ATTR_SORTABLE,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "When true, the field is exposed in generated CRUD sort allowlists. Inherits from @filterable by default; set false to opt out.",
+  },
+  {
+    name: FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...SORT_ORDER_VALUES],
+    description: "Default sort direction applied when this field is the default sort field.",
+  },
+  {
+    name: FIELD_ATTR_AUTO_SET,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...AUTO_SET_VALUES],
+    description:
+      "Auto-set semantics for timestamp-like fields: 'onCreate' stamps on insert, 'onUpdate' stamps on every write.",
+  },
+];
+
+/** The @currency attr — only on field.currency. */
+export const currencyFieldAttr: AttrSchema = {
+  name: FIELD_ATTR_CURRENCY,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  default: FIELD_ATTR_CURRENCY_DEFAULT,
+  description:
+    "ISO 4217 currency code for a currency-subtype field. Storage is integer minor units; defaults to 'USD' when omitted.",
+};

package/src/core/field/meta-field.ts

@@ -0,0 +1,179 @@
+// MetaField — concrete node class for type=field nodes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+// Children are already concrete typed nodes; accessors filter by type constant.
+
+import { MetaData, type AttrValue } from "../../shared/meta-data.js";
+import {
+  type DataType,
+  type DataTypeAware,
+  DATA_TYPE_STRING,
+  DATA_TYPE_INT,
+  DATA_TYPE_LONG,
+  DATA_TYPE_DOUBLE,
+  DATA_TYPE_BOOLEAN,
+  DATA_TYPE_DATE,
+  DATA_TYPE_OBJECT,
+} from "../../data-type.js";
+import { convertToDataType } from "../../data-converter.js";
+import { TYPE_VALIDATOR, TYPE_VIEW, SUBTYPE_BASE } from "../../shared/base-types.js";
+import {
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_UNIQUE,
+  FIELD_ATTR_DEFAULT,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_SCALE,
+  FIELD_ATTR_OBJECT_REF,
+} from "./field-constants.js";
+import { FIELD_ATTR_DB_COLUMN } from "../../persistence/db/db-constants.js";
+import { VALIDATOR_SUBTYPE_REQUIRED } from "../validator/validator-constants.js";
+import type { MetaValidator } from "../validator/meta-validator.js";
+import type { MetaView } from "../../presentation/view/meta-view.js";
+
+/** Field subtype → DataType. Co-located with the class — a provider adding a
+ *  field subtype supplies its own dataType the same way. */
+const FIELD_DATA_TYPE: Readonly<Record<string, DataType>> = {
+  [SUBTYPE_BASE]: DATA_TYPE_STRING,
+  [FIELD_SUBTYPE_STRING]: DATA_TYPE_STRING,
+  [FIELD_SUBTYPE_CLASS]: DATA_TYPE_STRING,
+  [FIELD_SUBTYPE_INT]: DATA_TYPE_INT,
+  [FIELD_SUBTYPE_SHORT]: DATA_TYPE_INT,
+  [FIELD_SUBTYPE_BYTE]: DATA_TYPE_INT,
+  [FIELD_SUBTYPE_LONG]: DATA_TYPE_LONG,
+  [FIELD_SUBTYPE_CURRENCY]: DATA_TYPE_LONG,
+  [FIELD_SUBTYPE_DOUBLE]: DATA_TYPE_DOUBLE,
+  [FIELD_SUBTYPE_FLOAT]: DATA_TYPE_DOUBLE,
+  [FIELD_SUBTYPE_DECIMAL]: DATA_TYPE_DOUBLE,
+  [FIELD_SUBTYPE_BOOLEAN]: DATA_TYPE_BOOLEAN,
+  [FIELD_SUBTYPE_DATE]: DATA_TYPE_DATE,
+  [FIELD_SUBTYPE_TIME]: DATA_TYPE_DATE,
+  [FIELD_SUBTYPE_TIMESTAMP]: DATA_TYPE_DATE,
+  [FIELD_SUBTYPE_OBJECT]: DATA_TYPE_OBJECT,
+};
+
+export class MetaField extends MetaData implements DataTypeAware {
+  /** The coarse value-type classification for this field's subtype. */
+  get dataType(): DataType {
+    return FIELD_DATA_TYPE[this.subType] ?? this._dataType ?? DATA_TYPE_STRING;
+  }
+
+  /** Coerce a raw value toward this field's DataType (Java DataConverter parity). */
+  coerce(raw: unknown): AttrValue {
+    return convertToDataType(this.dataType, raw);
+  }
+
+  /** The target object name for an object-typed field (the `@objectRef` attr). */
+  get objectRef(): string | undefined {
+    const v = this.ownAttr(FIELD_ATTR_OBJECT_REF);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  get dbColumn(): string | undefined {
+    const v = this.ownAttr(FIELD_ATTR_DB_COLUMN);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  get default(): unknown {
+    return this.ownAttr(FIELD_ATTR_DEFAULT);
+  }
+
+  /**
+   * The default value for this field, converted to the field's own DataType.
+   *
+   * Java parity: MetaField.getDefaultValue() — reads the raw @default attr and
+   * converts it via DataConverter.toTypeSafe(getDataType(), raw). This ensures
+   * that even if the raw value was stored as a string (e.g. "@default": "false"
+   * in YAML or string-keyed JSON), the returned value is the correctly-typed
+   * boolean/number/string for this field's subtype.
+   *
+   * Returns undefined when @default is not set on this field.
+   * Result is cached after freeze (same pattern as validators()/views()).
+   */
+  defaultValue(): AttrValue | undefined {
+    return this.cached("defaultValue", () => {
+      const raw = this.ownAttr(FIELD_ATTR_DEFAULT);
+      if (raw === undefined) return undefined;
+      return this.coerce(raw);
+    });
+  }
+
+  get maxLength(): number | undefined {
+    const v = this.ownAttr(FIELD_ATTR_MAX_LENGTH);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  get precision(): number | undefined {
+    const v = this.ownAttr(FIELD_ATTR_PRECISION);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  get scale(): number | undefined {
+    const v = this.ownAttr(FIELD_ATTR_SCALE);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  /** True if `@unique: true` is set on the field itself (column-level unique). */
+  get unique(): boolean {
+    return this.ownAttr(FIELD_ATTR_UNIQUE) === true;
+  }
+
+  /**
+   * True if the field is required (NOT NULL).
+   *
+   * Checks both `@required: true` attr and `validator.required` children —
+   * matches the codegen-ts isRequired() semantics.
+   */
+  get isRequired(): boolean {
+    if (this.ownAttr(FIELD_ATTR_REQUIRED) === true) return true;
+    return this.validators().some((v) => v.subType === VALIDATOR_SUBTYPE_REQUIRED);
+  }
+
+  /** All effective validators (own + inherited via extends). Java parity: MetaField.getValidators() / getChildren(MetaValidator.class, true). */
+  validators(): MetaValidator[] {
+    return this.cached("validators", () =>
+      this.children().filter((c): c is MetaValidator => c.type === TYPE_VALIDATOR),
+    );
+  }
+
+  /** Own validators only — excludes validators inherited via extends. Java parity: getChildren(Class, false). */
+  ownValidators(): MetaValidator[] {
+    return this.cached("ownValidators", () =>
+      this.ownChildren().filter((c): c is MetaValidator => c.type === TYPE_VALIDATOR),
+    );
+  }
+
+  /** All effective views (own + inherited via extends). Java parity: MetaField.getViews() / getChildren(MetaView.class, true). */
+  views(): MetaView[] {
+    return this.cached("views", () =>
+      this.children().filter((c): c is MetaView => c.type === TYPE_VIEW),
+    );
+  }
+
+  /** Own views only — excludes views inherited via extends. */
+  ownViews(): MetaView[] {
+    return this.cached("ownViews", () =>
+      this.ownChildren().filter((c): c is MetaView => c.type === TYPE_VIEW),
+    );
+  }
+
+  /** The typed supertype field if `extends:` resolved, else undefined. */
+  resolveSuper(): MetaField | undefined {
+    return this.superData as MetaField | undefined;
+  }
+}