@metaobjectsdev/runtime-ts 1.0.12 → 1.1.0

package/src/object-manager.ts

@@ -1,6 +1,9 @@
 import type { MetaData } from "@metaobjectsdev/metadata";
+import { physicalNamingGuideUrl } from "@metaobjectsdev/metadata/release-docs";
 import {
   TYPE_OBJECT, TYPE_FIELD,
+  OBJECT_SUBTYPE_REPORT,
+  isMetaObject, isMetaRoot, isReadOnlySource, reportReadModel,
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL,
 } from "@metaobjectsdev/metadata";
@@ -15,7 +18,7 @@ import {
 } from "./query-builder.js";
 import { tphSubtypeOf, type TphSubtype } from "./tph.js";
 import {
-  buildNameMap, resolveTableName, DEFAULT_COLUMN_NAMING_STRATEGY,
+  buildNameMap, resolveTableName, physicalNamingOf, physicalNamingRemovedMessage,
   type ColumnNamingStrategy, type EntityNameMap,
 } from "@metaobjectsdev/metadata";
 import { coerceRowOnRead, coerceRowOnWrite } from "./type-coercer.js";
@@ -41,12 +44,6 @@ import { VALID_ENTITY_NAME, DEFAULT_IF_MISSING } from "./constants.js";
 export interface ObjectManagerOptions {
   metadata: MetaData;
   driver: PersistenceDriver;
-  /**
-   * Column-naming strategy for fields with no `@column` override. Defaults to
-   * `"snake_case"`. Must agree with the codegen / migration config that
-   * created the schema (a mismatch yields columns the runtime can't address).
-   */
-  columnNamingStrategy?: ColumnNamingStrategy;
 }
 
 export interface ReadOpts extends QueryOpts {
@@ -70,7 +67,15 @@ export class ObjectManager {
   constructor(opts: ObjectManagerOptions) {
     this.metadata = opts.metadata;
     this.driver = opts.driver;
-    this.columnNamingStrategy = opts.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY;
+    // ADR-0058: the column rule is the project's one setting (`naming` in
+    // .metaobjects/config.json), carried by the loaded root — the same value codegen and
+    // `meta migrate` read, so the runtime cannot address columns the schema does not have.
+    // The 1.0 option is refused rather than dropped: its value may be the one that matches.
+    const removedNaming = (opts as { columnNamingStrategy?: unknown }).columnNamingStrategy;
+    if (removedNaming !== undefined) {
+      throw new Error(physicalNamingRemovedMessage("the ObjectManager columnNamingStrategy option", String(removedNaming), physicalNamingGuideUrl()));
+    }
+    this.columnNamingStrategy = physicalNamingOf(this.metadata).columns;
   }
 
   private nameMap(entity: MetaData): EntityNameMap {
@@ -111,7 +116,7 @@ export class ObjectManager {
   }
 
   async findById(entityName: string, id: unknown, opts: ReadOpts = {}): Promise<Row | null> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "findById");
     const pkField = resolvePkFields(entity)[0]!;
     return this.findFirst(entityName, { [pkField]: this.coerceIdArg(entity, id) as string | number }, opts);
   }
@@ -151,7 +156,7 @@ export class ObjectManager {
 
   async load(refString: string): Promise<Row | null> {
     const { entity: entityName, pkValues } = decodeRef(refString);
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "load");
     const pkFields = resolvePkFields(entity);
     if (pkValues.length !== pkFields.length) {
       throw new MetadataError(
@@ -169,12 +174,12 @@ export class ObjectManager {
   }
 
   refOf(entityName: string, record: Row): string {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "refOf");
     return encodeRef(entityName, record, resolvePkFields(entity));
   }
 
   async create(entityName: string, data: Row, opts: WriteOpts = {}): Promise<Row> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "create");
     const driver = opts.tx ?? this.driver;
 
     const restricted0 = this.applyViewRestriction(entity, data, opts.view);
@@ -197,7 +202,7 @@ export class ObjectManager {
   }
 
   async update(entityName: string, id: unknown, data: Row, opts: WriteOpts = {}): Promise<Row | null> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "update");
     const driver = opts.tx ?? this.driver;
 
     const restricted0 = this.applyViewRestriction(entity, data, opts.view);
@@ -229,7 +234,7 @@ export class ObjectManager {
   }
 
   async delete(entityName: string, id: unknown, opts: WriteOpts = {}): Promise<boolean> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "delete");
     const driver = opts.tx ?? this.driver;
     // FR-017 TPH: scope the by-id delete to the subtype (cross-subtype → not found).
     const spec = buildDeleteSpec(entity, this.coerceIdArg(entity, id), this.columnNamingStrategy, this.tphScope(entity));
@@ -243,7 +248,7 @@ export class ObjectManager {
   }
 
   async createMany(entityName: string, dataArray: Row[], opts: WriteOpts = {}): Promise<Row[]> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "createMany");
     const driver = opts.tx ?? this.driver;
 
     // Validate + identity-resolve every row before any insert so a late failure can't leave partial state.
@@ -274,7 +279,7 @@ export class ObjectManager {
   }
 
   async updateMany(entityName: string, filter: Filter, partial: Row, opts: WriteOpts = {}): Promise<number> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "updateMany");
     const driver = opts.tx ?? this.driver;
     const restricted = this.applyViewRestriction(entity, partial, opts.view);
     const v = runValidators(entity, restricted, { partial: true });
@@ -292,7 +297,7 @@ export class ObjectManager {
   }
 
   async deleteMany(entityName: string, filter: Filter, opts: WriteOpts = {}): Promise<number> {
-    const entity = this.requireEntity(entityName);
+    const entity = this.requireIdentified(entityName, "deleteMany");
     const driver = opts.tx ?? this.driver;
     const spec: DeleteManySpec = {
       table: resolveTableName(entity),
@@ -304,7 +309,7 @@ export class ObjectManager {
   async transaction<T>(fn: (txOm: ObjectManager) => Promise<T>): Promise<T> {
     return this.driver.transaction(async (txDriver) => {
       const txOm = new ObjectManager({
-        metadata: this.metadata, driver: txDriver, columnNamingStrategy: this.columnNamingStrategy,
+        metadata: this.metadata, driver: txDriver,
       });
       return fn(txOm);
     });
@@ -464,6 +469,12 @@ export class ObjectManager {
   }
 
   private requireEntity(entityName: string): MetaData {
+    const entity = this.requireObject(entityName);
+    return entity.subType === OBJECT_SUBTYPE_REPORT ? this.reportReadModelOf(entity) : entity;
+  }
+
+  /** The declared object node, exactly as loaded (a report is NOT swapped for its read model). */
+  private requireObject(entityName: string): MetaData {
     if (!VALID_ENTITY_NAME.test(entityName)) {
       throw new UnsafeNameError(
         `Unsafe entity name '${entityName}'`,
@@ -478,6 +489,57 @@ export class ObjectManager {
     return entity;
   }
 
+  /**
+   * FR-044: a report declares no fields — its read shape is derived — so it is read
+   * through a detached read model carrying one real field per derived field and the
+   * report's own read-only source. Everything downstream (column list, filter and
+   * sort resolution, the name map, read coercion) then treats it as it treats a
+   * projection. The model is built once per report node and never joins the tree.
+   *
+   * A report with no read-only source of its own has no view (Table A), so there is
+   * nothing to read: refused here rather than falling through to a default table name.
+   */
+  private reportReadModelOf(report: MetaData): MetaData {
+    if (!isMetaObject(report) || !isMetaRoot(this.metadata)) {
+      throw new MetadataError(
+        `Report '${report.name}' cannot be read: the ObjectManager's metadata is not a loaded root`,
+        { entity: report.name },
+      );
+    }
+    let model: MetaData;
+    try {
+      model = reportReadModel(report, this.metadata);
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      throw new MetadataError(`Report '${report.name}' cannot be read: ${detail}`, { entity: report.name, cause });
+    }
+    if (!model.children().some((c) => isReadOnlySource(c))) {
+      throw new MetadataError(
+        `Report '${report.name}' is not served: it declares no read-only source, so it has no view to read`,
+        { entity: report.name },
+      );
+    }
+    return model;
+  }
+
+  /**
+   * Resolve an entity for an operation that needs an identity or writes: get-by-id,
+   * reference encode/decode, and every create/update/delete. A report (FR-044) is an
+   * aggregate over a view — it has no primary key and no write target — so these are
+   * refused by name before anything else is looked at (a sourceless report included).
+   */
+  private requireIdentified(entityName: string, op: string): MetaData {
+    const entity = this.requireObject(entityName);
+    if (entity.subType === OBJECT_SUBTYPE_REPORT) {
+      throw new MetadataError(
+        `${op} is not supported on '${entityName}': a report is read-only and has no identity ` +
+          `(read it with findMany, findFirst or count)`,
+        { entity: entityName },
+      );
+    }
+    return entity;
+  }
+
   private toJsRow(entity: MetaData, dbRow: Row): Row {
     const { dbToJs } = this.nameMap(entity);
     const out: Row = {};

package/src/query-builder.ts

@@ -3,6 +3,7 @@ import {
   TYPE_FIELD, TYPE_IDENTITY,
   IDENTITY_SUBTYPE_PRIMARY,
   IDENTITY_ATTR_FIELDS,
+  OBJECT_SUBTYPE_REPORT,
   DEFAULT_COLUMN_NAMING_STRATEGY,
   resolveTableName, resolveColumnName,
 } from "@metaobjectsdev/metadata";
@@ -193,7 +194,19 @@ export function buildSelectSpec(
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): SelectSpec {
   const allFields = projectedFields ?? listFieldNames(entity);
-  const pkFields = resolvePkFields(entity);
+  // A report's read model (FR-044) has no identity, so there is no key to add to the
+  // column list. Scoped to the report subtype: every other object still requires one.
+  const isReport = entity.subType === OBJECT_SUBTYPE_REPORT;
+  // A report node as DECLARED has no field children (its shape is derived); only its
+  // read model does. Selecting from the bare node would be a query with no columns.
+  if (isReport && listFieldNames(entity).length === 0) {
+    throw new MetadataError(
+      `Report '${entity.name}' has no fields to select: a report is read through its read model ` +
+        `(reportReadModel), not through the declared node`,
+      { entity: entity.name },
+    );
+  }
+  const pkFields = isReport ? [] : resolvePkFields(entity);
   const fieldSet = new Set<string>(allFields);
   for (const pk of pkFields) fieldSet.add(pk);
 

package/src/relation-resolver.ts

@@ -6,6 +6,7 @@ import {
   CARDINALITY_ONE, CARDINALITY_MANY,
   DEFAULT_COLUMN_NAMING_STRATEGY,
   resolveRelationshipReference,
+  refTarget,
 } from "@metaobjectsdev/metadata";
 import { MetadataError } from "./errors.js";
 import {
@@ -31,7 +32,7 @@ export interface RelationDescriptor {
  */
 function findReferenceFkField(
   holder: MetaData,
-  targetName: string,
+  targetName: MetaData,
   relationshipName: string,
   sourceRefField?: string,
 ): string | undefined {
@@ -68,26 +69,26 @@ export function resolveRelationDescriptor(
         { entity: sourceEntity.name },
       );
     }
-    // ADR-0039: resolving — @sourceRefField may be inherited via extends.
-    const declaredRefField = child.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD) as string | undefined;
-    const fkField = findReferenceFkField(sourceEntity, targetEntityName, child.name, declaredRefField);
-    if (!fkField) {
+    // ADR-0059 R7: the target the loader bound, never a short-name match.
+    const target = refTarget(child, RELATIONSHIP_ATTR_OBJECT_REF);
+    if (!target || target.type !== TYPE_OBJECT) {
       throw new MetadataError(
-        `Relationship '${relationName}' on '${sourceEntity.name}' has no identity.reference targeting '${targetEntityName}'`,
+        `Target entity '${targetEntityName}' not found for relation '${relationName}' on '${sourceEntity.name}'`,
         { entity: sourceEntity.name },
       );
     }
-    // ADR-0039: effective children — resolve rather than rely on root being unextended.
-    const target = root.children().find((c) => c.type === TYPE_OBJECT && c.name === targetEntityName);
-    if (!target) {
+    // ADR-0039: resolving — @sourceRefField may be inherited via extends.
+    const declaredRefField = child.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD) as string | undefined;
+    const fkField = findReferenceFkField(sourceEntity, target, child.name, declaredRefField);
+    if (!fkField) {
       throw new MetadataError(
-        `Target entity '${targetEntityName}' not found for relation '${relationName}' on '${sourceEntity.name}'`,
+        `Relationship '${relationName}' on '${sourceEntity.name}' has no identity.reference targeting '${targetEntityName}'`,
         { entity: sourceEntity.name },
       );
     }
     return {
       cardinality: "one",
-      targetEntityName,
+      targetEntityName: target.name,
       sourceField: fkField,
       targetField: resolvePkFields(target)[0]!,
     };
@@ -103,15 +104,15 @@ export function resolveRelationDescriptor(
       // ADR-0039: effective attrs — @cardinality/@objectRef may be inherited.
       const card = child.attr(RELATIONSHIP_ATTR_CARDINALITY);
       if (card !== CARDINALITY_ONE) continue;
-      const targetEntityName = child.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
-      if (targetEntityName !== sourceEntity.name) continue;
+      // ADR-0059 R7: compare the bound target, not a name.
+      if (refTarget(child, RELATIONSHIP_ATTR_OBJECT_REF) !== sourceEntity) continue;
       const inverseName = inversePluralName(other.name);
       if (inverseName !== relationName) continue;
       // ADR-0039: resolving — @sourceRefField may be inherited via extends. This
       // FK lives on `other` and belongs to `other`'s own relationship `child` —
       // not to anything declared on sourceEntity (see #368 module comment).
       const declaredRefField = child.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD) as string | undefined;
-      const fkField = findReferenceFkField(other, sourceEntity.name, child.name, declaredRefField);
+      const fkField = findReferenceFkField(other, sourceEntity, child.name, declaredRefField);
       if (!fkField) {
         throw new MetadataError(
           `Inverse relationship for '${relationName}' on '${sourceEntity.name}': entity '${other.name}' has no identity.reference targeting '${sourceEntity.name}'`,

package/src/type-coercer.ts

@@ -3,6 +3,10 @@
 //  - SQLite has no native boolean: booleans are stored as 0/1 ints, so we map
 //    boolean↔int on the way in/out. MySQL's BOOLEAN is TINYINT(1) and mysql2 reads it
 //    back as 0/1, so it takes the same mapping.
+//  - field.decimal is the canonical decimal STRING on every dialect (ADR-0019 Amendment 1): a
+//    string Postgres/MySQL hand back loses its scale (`100.5000` -> `100.5`), a number SQLite/D1
+//    hand back is rendered at 15 significant digits, and a value written as a number or in
+//    exponent form is bound as its exact canonical string.
 //  - JSONB-backed object/map fields: the driver (node-postgres) does NOT
 //    serialize a plain JS object to a jsonb column — it must arrive as a JSON
 //    string, or the write fails / writes "[object Object]". A `field.object`
@@ -14,25 +18,32 @@
 // strings for temporal columns directly, and the temporal read parsers pin the
 // wire form.
 
-import type { MetaData } from "@metaobjectsdev/metadata";
+import { refTarget, type MetaData } from "@metaobjectsdev/metadata";
 import {
   TYPE_FIELD,
   FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_MAP,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_ATTR_STORAGE,
+  FIELD_ATTR_OBJECT_REF,
+  OBJECT_SUBTYPE_VALUE,
   FIELD_ATTR_DB_COLUMN_TYPE,
   FIELD_ATTR_INT_VALUE_MAP,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_SCALE,
   STORAGE_JSONB,
   STORAGE_FLATTENED,
   DB_COLUMN_TYPE_JSONB,
 } from "@metaobjectsdev/metadata";
 import type { Dialect, Row } from "./persistence-driver.js";
+import { decimalFits, decimalToWire, parseDecimalInput } from "./decimal-wire.js";
 
 export function coerceRowOnRead(entity: MetaData, row: Row, dialect: Dialect): Row {
   const hydrated = parseJsonTextArrays(entity, deserializeJsonbObjectFields(entity, row));
-  const decoded = decodeIntBackedEnums(entity, hydrated);
+  const decoded = canonicalizeDecimals(entity, decodeIntBackedEnums(entity, hydrated));
   if (dialect !== "sqlite" && dialect !== "mysql") return decoded;
   return mapBooleansFromInt(entity, decoded);
 }
@@ -130,7 +141,7 @@ function encodeIntBackedEnums(entity: MetaData, row: Row): Row {
 }
 
 export function coerceRowOnWrite(entity: MetaData, row: Row, dialect: Dialect): Row {
-  const jsonbColumned = serializeJsonbColumns(entity, row);
+  const jsonbColumned = serializeJsonbColumns(entity, bindDecimals(entity, row));
   // Dialect-independent: an int-backed enum's column is INTEGER on every dialect
   // (SQLite has one integer storage class), so the symbol→int encode is not gated
   // on the dialect the way the boolean mapping below is.
@@ -212,8 +223,10 @@ function mapBooleansFromInt(entity: MetaData, row: Row): Row {
     if (child.type !== TYPE_FIELD) continue;
     if (child.subType !== FIELD_SUBTYPE_BOOLEAN) continue;
     const v = out[child.name];
-    if (v === 0) out[child.name] = false;
-    else if (v === 1) out[child.name] = true;
+    // A report's boolean measure (`@agg: any` / `all`) under a condition is a MySQL BIGINT, which
+    // the pool's `bigNumberStrings` hands back as text; a plain TINYINT(1) arrives as a number.
+    if (v === 0 || v === "0") out[child.name] = false;
+    else if (v === 1 || v === "1") out[child.name] = true;
   }
   return out;
 }
@@ -279,3 +292,101 @@ function parseJsonTextArrays(entity: MetaData, row: Row): Row {
   }
   return out ?? row;
 }
+
+/** The `object.value` a jsonb `field.object` references, or undefined (not a value object, or unresolved). */
+function valueObjectOf(field: MetaData): MetaData | undefined {
+  // A field.map of value objects binds @objectRef the same way (its values are the value objects).
+  if (field.type !== TYPE_FIELD || (field.subType !== FIELD_SUBTYPE_OBJECT && field.subType !== FIELD_SUBTYPE_MAP)) return undefined;
+  // ADR-0059 R7: the object the loader bound @objectRef to.
+  const target = refTarget(field, FIELD_ATTR_OBJECT_REF);
+  return target?.subType === OBJECT_SUBTYPE_VALUE ? target : undefined;
+}
+
+/**
+ * Apply `convert` to every `field.decimal` of `owner` present in `row`, and recurse into a
+ * `field.object` whose value object declares decimals (captain ruling C1: a decimal inside a
+ * jsonb value object follows the top-level rule). `convert` answers the new value; a row, an
+ * object or an array is copied only when something changed.
+ */
+function mapDecimals(
+  owner: MetaData,
+  row: Row,
+  convert: (field: MetaData, value: unknown) => unknown,
+): Row {
+  let out: Row | null = null;
+  // Effective children (ADR-0039): a decimal may be inherited via extends, and a report's
+  // derived ratio / average / sum is a decimal field of the report itself.
+  for (const child of owner.children()) {
+    if (child.type !== TYPE_FIELD) continue;
+    if (!(child.name in row)) continue;
+    const v = row[child.name];
+    if (v === null || v === undefined) continue;
+    let next: unknown = v;
+    if (child.subType === FIELD_SUBTYPE_DECIMAL) {
+      next = convert(child, v);
+    } else {
+      const vo = valueObjectOf(child);
+      if (vo === undefined) continue;
+      const one = (el: unknown): unknown =>
+        el !== null && typeof el === "object" && !Array.isArray(el) ? mapDecimals(vo, el as Row, convert) : el;
+      if (child.subType === FIELD_SUBTYPE_MAP) {
+        // The rule applies to EACH map value; keys are arbitrary text, never compared with the
+        // value object's member names (a key named `amount` is just a key).
+        if (typeof v === "object" && !Array.isArray(v)) {
+          let mapped: Row | null = null;
+          for (const [key, el] of Object.entries(v as Row)) {
+            const m = one(el);
+            if (m !== el) (mapped ??= { ...(v as Row) })[key] = m;
+          }
+          if (mapped !== null) next = mapped;
+        }
+      } else if (Array.isArray(v)) {
+        const mapped = v.map(one);
+        if (mapped.some((el, i) => el !== v[i])) next = mapped;
+      } else {
+        next = one(v);
+      }
+    }
+    if (next === v) continue;
+    out ??= { ...row };
+    out[child.name] = next;
+  }
+  return out ?? row;
+}
+
+/** Read side: every `field.decimal` the row carries becomes its canonical string. */
+function canonicalizeDecimals(entity: MetaData, row: Row): Row {
+  return mapDecimals(entity, row, (_field, v) => decimalToWire(v));
+}
+
+/**
+ * Write side: a `field.decimal` value is bound as its exact canonical string, and a decimal
+ * declared `isArray` as an array of them. A string in the JSON-number grammar or a number a double
+ * holds exactly is accepted; anything else, or a value the declared `@precision` / `@scale` cannot
+ * hold (W3), is refused here rather than reaching a column that would round it, reject it with a
+ * driver error, or store garbage. A decimal inside a jsonb value object is bound the same way.
+ */
+function bindDecimals(entity: MetaData, row: Row): Row {
+  return mapDecimals(entity, row, (child, v) => {
+    // ADR-0039: resolving — a decimal, its isArray and its @precision / @scale may be inherited.
+    const precision = child.attr(FIELD_ATTR_PRECISION);
+    const scale = child.attr(FIELD_ATTR_SCALE);
+    const bind = (value: unknown): string => {
+      const canonical = parseDecimalInput(value);
+      if (canonical === undefined) {
+        throw new Error(`field.decimal '${child.name}' cannot be written: ${JSON.stringify(value)} is not a decimal number (a string in the JSON-number grammar, or a number a double holds exactly: send a string for more than 15 significant digits)`);
+      }
+      if (!decimalFits(canonical, typeof precision === "number" ? precision : undefined, typeof scale === "number" ? scale : undefined)) {
+        throw new Error(`field.decimal '${child.name}' cannot be written: ${canonical} does not fit @precision ${String(precision)} / @scale ${String(scale ?? 0)}`);
+      }
+      return canonical;
+    };
+    if (child.resolvedIsArray()) {
+      if (!Array.isArray(v)) {
+        throw new Error(`field.decimal '${child.name}' cannot be written: ${JSON.stringify(v)} is not an array of decimal numbers`);
+      }
+      return v.map((element) => (element === null ? null : bind(element)));
+    }
+    return bind(v);
+  });
+}