@metaobjectsdev/runtime-ts 1.0.9 → 1.0.11

package/src/persistence-driver.ts

@@ -2,7 +2,7 @@
 // The driver IS the unit of transaction — transaction(fn) yields a tx-scoped sub-driver.
 // Java analog: ObjectConnection.
 
-export type Dialect = "sqlite" | "postgres" | "memory";
+export type Dialect = "sqlite" | "postgres" | "mysql" | "memory";
 
 export type PrimitiveValue = string | number | boolean;
 
@@ -42,12 +42,19 @@ export interface InsertSpec {
   values: Row;
   /** Columns to return — driver handles RETURNING / lastInsertId per dialect. */
   returning: string[];
+  /**
+   * The primary-key columns. A dialect without RETURNING (MySQL) reads the inserted row
+   * back by them; the others ignore it.
+   */
+  key?: string[];
 }
 
 export interface InsertManySpec {
   table: string;
   rows: Row[];
   returning: string[];
+  /** As {@link InsertSpec.key}. */
+  key?: string[];
 }
 
 export interface UpdateSpec {

package/src/query-builder.ts

@@ -232,9 +232,18 @@ export function buildInsertSpec(
     table: resolveTableName(entity),
     values,
     returning: allFields.map((f) => resolveColumnName(getField(entity, f), strategy)),
+    key: primaryKeyColumns(entity, strategy),
   };
 }
 
+/** The primary-key COLUMN names (a driver without RETURNING reads an insert back by them). */
+export function primaryKeyColumns(
+  entity: MetaData,
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+): string[] {
+  return resolvePkFields(entity).map((f) => resolveColumnName(getField(entity, f), strategy));
+}
+
 /**
  * A TPH discriminator scope: AND'd into the by-id where so a subtype-scoped
  * update/delete only matches rows of that subtype (a row of a different

package/src/sql-dialect.ts

@@ -0,0 +1,21 @@
+/**
+ * The SQL dialects the runtime mounts and drivers speak. `mysql` is a codegen + runtime dialect
+ * only: MetaObjects does not own a MySQL schema (`meta migrate` supports Postgres, SQLite and
+ * D1), so the adopter writes the DDL.
+ */
+export type SqlDialect = "sqlite" | "postgres" | "mysql";
+
+/** Whether the dialect's INSERT / UPDATE / DELETE can return rows (`RETURNING`). MySQL cannot. */
+export function supportsReturning(dialect: SqlDialect | undefined): boolean {
+  return dialect !== "mysql";
+}
+
+/** Quote an identifier for raw SQL: backticks on MySQL, double quotes elsewhere. */
+export function quoteIdent(dialect: SqlDialect | undefined, name: string): string {
+  if (dialect === "mysql") {
+    if (name.includes("`")) throw new Error(`unsafe identifier: ${name}`);
+    return `\`${name}\``;
+  }
+  if (name.includes('"')) throw new Error(`unsafe identifier: ${name}`);
+  return `"${name}"`;
+}

package/src/type-coercer.ts

@@ -1,7 +1,8 @@
 // Read/write value coercion at the persistence boundary.
 //
 //  - SQLite has no native boolean: booleans are stored as 0/1 ints, so we map
-//    boolean↔int on the way in/out for that dialect only.
+//    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.
 //  - 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`
@@ -19,6 +20,7 @@ import {
   FIELD_SUBTYPE_BOOLEAN,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_TIMESTAMP,
   FIELD_ATTR_STORAGE,
   FIELD_ATTR_DB_COLUMN_TYPE,
   FIELD_ATTR_INT_VALUE_MAP,
@@ -29,9 +31,9 @@ import {
 import type { Dialect, Row } from "./persistence-driver.js";
 
 export function coerceRowOnRead(entity: MetaData, row: Row, dialect: Dialect): Row {
-  const hydrated = deserializeJsonbObjectFields(entity, row);
+  const hydrated = parseJsonTextArrays(entity, deserializeJsonbObjectFields(entity, row));
   const decoded = decodeIntBackedEnums(entity, hydrated);
-  if (dialect !== "sqlite") return decoded;
+  if (dialect !== "sqlite" && dialect !== "mysql") return decoded;
   return mapBooleansFromInt(entity, decoded);
 }
 
@@ -133,6 +135,7 @@ export function coerceRowOnWrite(entity: MetaData, row: Row, dialect: 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.
   const encoded = encodeIntBackedEnums(entity, jsonbColumned);
+  if (dialect === "mysql") return mapBooleansToInt(entity, isoTimestampsToDates(entity, encoded));
   if (dialect !== "sqlite") return encoded;
   return mapBooleansToInt(entity, encoded);
 }
@@ -227,3 +230,52 @@ function mapBooleansToInt(entity: MetaData, row: Row): Row {
   }
   return out;
 }
+
+/**
+ * MySQL: a `DATETIME` rejects the ISO wire form (`…T…Z` is ERROR 1292), so a
+ * `field.timestamp` string is handed to the driver as a `Date`. mysql2 writes it in the
+ * pool's `timezone` and reads it back the same way, so the instant round-trips; create the
+ * pool with `timezone: "Z"` to store the UTC wall clock, as the generated Drizzle tier and
+ * the Java port do.
+ */
+function isoTimestampsToDates(entity: MetaData, row: Row): Row {
+  let out: Row | null = null;
+  // ADR-0039: resolving — a timestamp may be inherited from a base via extends.
+  for (const child of entity.children()) {
+    if (child.type !== TYPE_FIELD || child.subType !== FIELD_SUBTYPE_TIMESTAMP) continue;
+    if (!(child.name in row)) continue;
+    const v = row[child.name];
+    if (typeof v !== "string") continue;
+    const d = new Date(v);
+    if (Number.isNaN(d.getTime())) continue;
+    out ??= { ...row };
+    out[child.name] = d;
+  }
+  return out ?? row;
+}
+
+/**
+ * A scalar array (`field.string isArray`, …) read back as JSON TEXT — SQLite's JSON-in-TEXT
+ * column through a driver that does not parse it (Kysely) — becomes the array again. A
+ * value that is already an array (Postgres native arrays, mysql2's parsed JSON, Drizzle's
+ * JSON column modes) passes through.
+ */
+function parseJsonTextArrays(entity: MetaData, row: Row): Row {
+  let out: Row | null = null;
+  // ADR-0039: resolving — an array field may be inherited via extends.
+  for (const child of entity.children()) {
+    if (child.type !== TYPE_FIELD || child.subType === FIELD_SUBTYPE_OBJECT) continue;
+    if (!child.resolvedIsArray()) continue;
+    const v = row[child.name];
+    if (typeof v !== "string" || !v.startsWith("[")) continue;
+    try {
+      const parsed: unknown = JSON.parse(v);
+      if (!Array.isArray(parsed)) continue;
+      out ??= { ...row };
+      out[child.name] = parsed;
+    } catch {
+      // Not JSON: leave the stored text as it is.
+    }
+  }
+  return out ?? row;
+}

package/src/validator-runner.ts

@@ -108,7 +108,7 @@ export function runValidators(
     if (field.subType === FIELD_SUBTYPE_OBJECT) {
       const vo = resolveVoRef(field);
       if (vo !== undefined) {
-        if (field.isArray && !Array.isArray(value)) {
+        if (field.resolvedIsArray() && !Array.isArray(value)) {
           errors.push({
             field: field.name, rule: "type",
             message: `'${field.name}' must be an array of ${vo.name}`,
@@ -116,7 +116,7 @@ export function runValidators(
           });
           continue;
         }
-        const elements: unknown[] = field.isArray ? (value as unknown[]) : [value];
+        const elements: unknown[] = field.resolvedIsArray() ? (value as unknown[]) : [value];
         elements.forEach((el, i) => {
           if (typeof el !== "object" || el === null || Array.isArray(el)) {
             errors.push({
@@ -131,7 +131,7 @@ export function runValidators(
             for (const e of sub.errors) {
               errors.push({
                 ...e,
-                field: field.isArray ? `${field.name}[${i}].${e.field}` : `${field.name}.${e.field}`,
+                field: field.resolvedIsArray() ? `${field.name}[${i}].${e.field}` : `${field.name}.${e.field}`,
               });
             }
           }
@@ -140,78 +140,26 @@ export function runValidators(
       continue;
     }
 
-    const typeError = checkType(field.subType, value);
-    if (typeError !== null) {
-      errors.push({
-        field: field.name,
-        rule: "type",
-        message: typeError,
-        expected: field.subType,
-        received: typeof value,
-      });
-      continue;
-    }
-
-    const maxLen = resolveMaxLength(field);
-    const minLen = resolveMinLength(field);
-    if (typeof value === "string") {
-      if (maxLen !== undefined && value.length > maxLen) {
-        errors.push({
-          field: field.name,
-          rule: "length",
-          message: `'${field.name}' must be at most ${maxLen} chars (got ${value.length})`,
-          expected: { max: maxLen },
-          received: value.length,
-        });
-      }
-      // FR-036 Pin 1: a @required string is non-empty. The effective floor is
-      // max(@min, 1) so the runtime OM rejects "" for a required string exactly as
-      // the generated Zod InsertSchema (.min(1)) does — the two enforcement surfaces
-      // stay in lockstep. A non-required field keeps its authored @min.
-      const effectiveMin = Math.max(minLen ?? 0, required ? 1 : 0);
-      if (effectiveMin > 0 && value.length < effectiveMin) {
-        errors.push({
-          field: field.name,
-          rule: "length",
-          message: `'${field.name}' must be at least ${effectiveMin} chars (got ${value.length})`,
-          expected: { min: effectiveMin },
-          received: value.length,
-        });
-      }
-    }
-
-    // ADR-0039: effective children — a validator may be inherited via extends.
-    for (const child of field.children()) {
-      if (child.type !== TYPE_VALIDATOR) continue;
-      if (child.subType !== VALIDATOR_SUBTYPE_REGEX) continue;
-      // ADR-0039: effective attr — @pattern may be inherited.
-      const pattern = child.attr(VALIDATOR_ATTR_PATTERN);
-      if (typeof pattern !== "string") continue;
-      if (typeof value !== "string") continue;
-      let regex: RegExp;
-      try {
-        // FR-036 Pin 2: validator.regex @pattern is FULL-MATCH — anchor as ^(?:…)$
-        // so the runtime OM matches the generated Zod schema's full-match semantic.
-        regex = new RegExp(`^(?:${pattern})$`);
-      } catch {
+    // A scalar array (`field.string isArray`, …) — stored as a native array or a JSON array.
+    // Each element is checked against the element rules; an element error names its index,
+    // as the value-object branch above does. ADR-0039: resolving `isArray`.
+    if (field.resolvedIsArray()) {
+      if (!Array.isArray(value)) {
         errors.push({
-          field: field.name,
-          rule: "regex",
-          message: `'${field.name}' has an invalid validator pattern: ${pattern}`,
-          expected: pattern,
+          field: field.name, rule: "type",
+          message: `'${field.name}' must be an array`,
+          expected: "array", received: typeof value,
         });
         continue;
       }
-      if (!regex.test(value)) {
-        errors.push({
-          field: field.name,
-          rule: "regex",
-          message: `'${field.name}' does not match required pattern`,
-          expected: pattern,
-          received: value,
-        });
-      }
+      value.forEach((el, i) => {
+        if (el === null || el === undefined) return;
+        errors.push(...scalarErrors(field, el, false, `${field.name}[${i}]`));
+      });
+      continue;
     }
+
+    errors.push(...scalarErrors(field, value, required, field.name));
   }
 
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
@@ -288,3 +236,85 @@ function checkType(subType: string, value: unknown): string | null {
   }
   return null;
 }
+
+/**
+ * The type, length and regex errors for one scalar value of `field` — the whole field
+ * value, or one element of a scalar array (then `required` is false: element presence is not
+ * the field's `@required`, and `label` is `name[i]`).
+ */
+function scalarErrors(field: MetaData, value: unknown, required: boolean, label: string): ValidationFailure[] {
+  const errors: ValidationFailure[] = [];
+  const typeError = checkType(field.subType, value);
+  if (typeError !== null) {
+    errors.push({
+      field: label,
+      rule: "type",
+      message: typeError,
+      expected: field.subType,
+      received: typeof value,
+    });
+    return errors;
+  }
+
+  const maxLen = resolveMaxLength(field);
+  const minLen = resolveMinLength(field);
+  if (typeof value === "string") {
+    if (maxLen !== undefined && value.length > maxLen) {
+      errors.push({
+        field: label,
+        rule: "length",
+        message: `'${label}' must be at most ${maxLen} chars (got ${value.length})`,
+        expected: { max: maxLen },
+        received: value.length,
+      });
+    }
+    // FR-036 Pin 1: a @required string is non-empty. The effective floor is
+    // max(@min, 1) so the runtime OM rejects "" for a required string exactly as
+    // the generated Zod InsertSchema (.min(1)) does — the two enforcement surfaces
+    // stay in lockstep. A non-required field keeps its authored @min.
+    const effectiveMin = Math.max(minLen ?? 0, required ? 1 : 0);
+    if (effectiveMin > 0 && value.length < effectiveMin) {
+      errors.push({
+        field: label,
+        rule: "length",
+        message: `'${label}' must be at least ${effectiveMin} chars (got ${value.length})`,
+        expected: { min: effectiveMin },
+        received: value.length,
+      });
+    }
+  }
+
+  // ADR-0039: effective children — a validator may be inherited via extends.
+  for (const child of field.children()) {
+    if (child.type !== TYPE_VALIDATOR) continue;
+    if (child.subType !== VALIDATOR_SUBTYPE_REGEX) continue;
+    // ADR-0039: effective attr — @pattern may be inherited.
+    const pattern = child.attr(VALIDATOR_ATTR_PATTERN);
+    if (typeof pattern !== "string") continue;
+    if (typeof value !== "string") continue;
+    let regex: RegExp;
+    try {
+      // FR-036 Pin 2: validator.regex @pattern is FULL-MATCH — anchor as ^(?:…)$
+      // so the runtime OM matches the generated Zod schema's full-match semantic.
+      regex = new RegExp(`^(?:${pattern})$`);
+    } catch {
+      errors.push({
+        field: label,
+        rule: "regex",
+        message: `'${label}' has an invalid validator pattern: ${pattern}`,
+        expected: pattern,
+      });
+      continue;
+    }
+    if (!regex.test(value)) {
+      errors.push({
+        field: label,
+        rule: "regex",
+        message: `'${label}' does not match required pattern`,
+        expected: pattern,
+        received: value,
+      });
+    }
+  }
+  return errors;
+}