@jskit-ai/database-runtime-mysql 0.1.15 → 0.1.17

package/package.descriptor.mjs

@@ -1,7 +1,8 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/database-runtime-mysql",
-  version: "0.1.15",
+  version: "0.1.17",
+  kind: "runtime",
   options: {
     "db-host": {
       required: false,
@@ -90,7 +91,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/database-runtime": "0.1.16",
+        "@jskit-ai/database-runtime": "0.1.18",
         "mysql2": "^3.11.2"
       },
       dev: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/database-runtime-mysql",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -12,6 +12,6 @@
     "./shared/dialect": "./src/shared/dialect.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.16"
+    "@jskit-ai/database-runtime": "0.1.18"
   }
 }

package/src/server/providers/DatabaseRuntimeMysqlServiceProvider.js

@@ -1,20 +1,18 @@
 import * as mysqlDialect from "../../shared/index.js";
 
-const DATABASE_DRIVER_MYSQL_TOKEN = "runtime.database.driver.mysql";
-
 const MYSQL_DATABASE_DRIVER_API = Object.freeze({
   ...mysqlDialect
 });
 
 class DatabaseRuntimeMysqlServiceProvider {
-  static id = DATABASE_DRIVER_MYSQL_TOKEN;
+  static id = "runtime.database.driver.mysql";
 
   register(app) {
     if (!app || typeof app.singleton !== "function") {
       throw new Error("DatabaseRuntimeMysqlServiceProvider requires application singleton().");
     }
 
-    app.singleton(DATABASE_DRIVER_MYSQL_TOKEN, () => MYSQL_DATABASE_DRIVER_API);
+    app.singleton("runtime.database.driver.mysql", () => MYSQL_DATABASE_DRIVER_API);
   }
 
   boot() {}

package/src/shared/index.js

@@ -1 +1,2 @@
 export { DIALECT_ID, getDialectId } from "./dialect.js";
+export { introspectCrudTableSnapshot } from "./introspectCrudTable.js";

package/src/shared/introspectCrudTable.js

@@ -0,0 +1,384 @@
+import { normalizeText } from "@jskit-ai/database-runtime/shared";
+import { toCamelCase } from "@jskit-ai/kernel/shared/support/stringCase";
+
+const BOOLEAN_TINYINT_PATTERN = /^tinyint\(1\)/;
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_]+$/;
+
+function requireKnexRaw(knex) {
+  if (!knex || typeof knex.raw !== "function") {
+    throw new TypeError("introspectCrudTableSnapshot requires knex with raw().");
+  }
+}
+
+function requireTableName(value) {
+  const tableName = normalizeText(value);
+  if (!tableName) {
+    throw new TypeError("introspectCrudTableSnapshot requires tableName.");
+  }
+  if (!TABLE_NAME_PATTERN.test(tableName)) {
+    throw new Error(`Invalid table name "${tableName}". Use letters, numbers, and underscore only.`);
+  }
+
+  return tableName;
+}
+
+function normalizeRows(rawResult) {
+  if (Array.isArray(rawResult)) {
+    if (rawResult.length > 0 && Array.isArray(rawResult[0])) {
+      return rawResult[0];
+    }
+    return rawResult;
+  }
+  if (rawResult && typeof rawResult === "object" && Array.isArray(rawResult.rows)) {
+    return rawResult.rows;
+  }
+  return [];
+}
+
+function normalizeDbSchemaName(rows = []) {
+  const firstRow = Array.isArray(rows) ? rows[0] : null;
+  const schemaName = normalizeText(firstRow?.schemaName || firstRow?.schema_name || "");
+  if (!schemaName) {
+    throw new Error("Could not resolve current database schema name.");
+  }
+
+  return schemaName;
+}
+
+function toBoolean(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return value !== 0;
+  }
+  const text = normalizeText(value).toLowerCase();
+  return text === "1" || text === "true" || text === "yes" || text === "y";
+}
+
+function toNullableNumber(value) {
+  if (value == null) {
+    return null;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function normalizeColumnDefault(value) {
+  if (value == null) {
+    return null;
+  }
+
+  const normalized = normalizeText(value).toLowerCase();
+  if (normalized === "null") {
+    return null;
+  }
+
+  return value;
+}
+
+function parseEnumValues(columnType = "") {
+  const source = normalizeText(columnType);
+  if (!source.toLowerCase().startsWith("enum(") || !source.endsWith(")")) {
+    return Object.freeze([]);
+  }
+
+  const body = source.slice(5, -1);
+  const values = [];
+  const pattern = /'((?:\\'|[^'])*)'/g;
+  let match = null;
+  while ((match = pattern.exec(body)) != null) {
+    values.push(match[1].replace(/\\'/g, "'"));
+  }
+  return Object.freeze(values);
+}
+
+function resolveTypeKind(column) {
+  const dataType = normalizeText(column?.dataType).toLowerCase();
+  const columnType = normalizeText(column?.columnType).toLowerCase();
+
+  if (
+    dataType === "varchar" ||
+    dataType === "char" ||
+    dataType === "text" ||
+    dataType === "tinytext" ||
+    dataType === "mediumtext" ||
+    dataType === "longtext" ||
+    dataType === "enum" ||
+    dataType === "set"
+  ) {
+    return "string";
+  }
+
+  if (
+    dataType === "int" ||
+    dataType === "integer" ||
+    dataType === "smallint" ||
+    dataType === "mediumint" ||
+    dataType === "bigint"
+  ) {
+    return "integer";
+  }
+
+  if (dataType === "tinyint") {
+    if (BOOLEAN_TINYINT_PATTERN.test(columnType)) {
+      return "boolean";
+    }
+    return "integer";
+  }
+
+  if (
+    dataType === "decimal" ||
+    dataType === "numeric" ||
+    dataType === "float" ||
+    dataType === "double" ||
+    dataType === "real"
+  ) {
+    return "number";
+  }
+
+  if (dataType === "boolean" || dataType === "bool") {
+    return "boolean";
+  }
+
+  if (dataType === "datetime" || dataType === "timestamp") {
+    return "datetime";
+  }
+  if (dataType === "date") {
+    return "date";
+  }
+  if (dataType === "time") {
+    return "time";
+  }
+  if (dataType === "json") {
+    return "json";
+  }
+
+  throw new Error(
+    `Unsupported MySQL column type "${dataType}" for column "${String(column?.name || "")}".`
+  );
+}
+
+function normalizeColumn(row = {}) {
+  const name = normalizeText(row.columnName || row.column_name);
+  if (!name) {
+    throw new Error("MySQL introspection returned a column without column name.");
+  }
+
+  const dataType = normalizeText(row.dataType || row.data_type).toLowerCase();
+  const columnType = normalizeText(row.columnType || row.column_type);
+  const columnTypeLower = columnType.toLowerCase();
+  const nullable = normalizeText(row.isNullable || row.is_nullable).toUpperCase() === "YES";
+  const rawDefaultValue = Object.prototype.hasOwnProperty.call(row, "columnDefault")
+    ? row.columnDefault
+    : Object.prototype.hasOwnProperty.call(row, "column_default")
+      ? row.column_default
+      : null;
+  const defaultValue = normalizeColumnDefault(rawDefaultValue);
+  const hasDefault = defaultValue != null;
+  const extra = normalizeText(row.extra).toLowerCase();
+  const autoIncrement = extra.includes("auto_increment");
+  const unsigned = columnTypeLower.includes("unsigned");
+  const enumValues = parseEnumValues(columnType);
+
+  const normalized = Object.freeze({
+    name,
+    key: toCamelCase(name),
+    dataType,
+    columnType,
+    extra,
+    typeKind: resolveTypeKind({
+      name,
+      dataType,
+      columnType
+    }),
+    nullable,
+    defaultValue,
+    hasDefault,
+    autoIncrement,
+    unsigned,
+    maxLength: toNullableNumber(row.characterMaximumLength ?? row.character_maximum_length),
+    numericPrecision: toNullableNumber(row.numericPrecision ?? row.numeric_precision),
+    numericScale: toNullableNumber(row.numericScale ?? row.numeric_scale),
+    datetimePrecision: toNullableNumber(row.datetimePrecision ?? row.datetime_precision),
+    ordinalPosition: toNullableNumber(row.ordinalPosition ?? row.ordinal_position),
+    enumValues
+  });
+
+  return normalized;
+}
+
+function normalizePrimaryKeyColumns(rows = []) {
+  return Object.freeze(
+    rows
+      .map((row) => normalizeText(row.columnName || row.column_name))
+      .filter(Boolean)
+  );
+}
+
+function normalizeIndexes(rows = []) {
+  const byName = new Map();
+
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const indexName = normalizeText(row.indexName || row.index_name);
+    const columnName = normalizeText(row.columnName || row.column_name);
+    if (!indexName || !columnName) {
+      continue;
+    }
+
+    const seqInIndex = toNullableNumber(row.seqInIndex ?? row.seq_in_index) || 0;
+    const nonUnique = toBoolean(row.nonUnique ?? row.non_unique);
+    const existing = byName.get(indexName) || {
+      name: indexName,
+      unique: !nonUnique,
+      columns: []
+    };
+    existing.columns.push({
+      name: columnName,
+      order: seqInIndex
+    });
+    byName.set(indexName, existing);
+  }
+
+  return Object.freeze(
+    [...byName.values()]
+      .map((index) =>
+        Object.freeze({
+          name: index.name,
+          unique: index.unique,
+          columns: Object.freeze(
+            index.columns
+              .sort((left, right) => left.order - right.order)
+              .map((column) => column.name)
+          )
+        })
+      )
+      .sort((left, right) => left.name.localeCompare(right.name))
+  );
+}
+
+function requireIdColumn(columns, idColumn) {
+  const normalizedIdColumn = normalizeText(idColumn) || "id";
+  const idSpec = columns.find((column) => column.name === normalizedIdColumn) || null;
+  if (!idSpec) {
+    throw new Error(`Could not find id column "${normalizedIdColumn}" in table.`);
+  }
+  if (idSpec.typeKind !== "integer") {
+    throw new Error(`Id column "${normalizedIdColumn}" must use an integer type.`);
+  }
+  if (idSpec.nullable) {
+    throw new Error(`Id column "${normalizedIdColumn}" must be not-null.`);
+  }
+  if (!idSpec.autoIncrement && !idSpec.hasDefault) {
+    throw new Error(
+      `Id column "${normalizedIdColumn}" must be auto_increment or have a database default.`
+    );
+  }
+
+  return normalizedIdColumn;
+}
+
+function requirePrimaryKeyContainsId(primaryKeyColumns, idColumn) {
+  if (!Array.isArray(primaryKeyColumns) || !primaryKeyColumns.includes(idColumn)) {
+    throw new Error(`Primary key must include id column "${idColumn}".`);
+  }
+  if (primaryKeyColumns.length !== 1 || primaryKeyColumns[0] !== idColumn) {
+    throw new Error(
+      `Composite primary keys are not supported for CRUD generation. Primary key must be only "${idColumn}".`
+    );
+  }
+}
+
+async function introspectCrudTableSnapshot(knex, { tableName = "", idColumn = "id" } = {}) {
+  requireKnexRaw(knex);
+  const resolvedTableName = requireTableName(tableName);
+
+  const schemaRows = normalizeRows(await knex.raw("SELECT DATABASE() AS schemaName"));
+  const schemaName = normalizeDbSchemaName(schemaRows);
+
+  const columnRows = normalizeRows(
+    await knex.raw(
+      `
+        SELECT
+          c.column_name AS columnName,
+          c.data_type AS dataType,
+          c.column_type AS columnType,
+          c.is_nullable AS isNullable,
+          c.column_default AS columnDefault,
+          c.extra AS extra,
+          c.character_maximum_length AS characterMaximumLength,
+          c.numeric_precision AS numericPrecision,
+          c.numeric_scale AS numericScale,
+          c.datetime_precision AS datetimePrecision,
+          c.ordinal_position AS ordinalPosition
+        FROM information_schema.columns c
+        WHERE c.table_schema = ?
+          AND c.table_name = ?
+        ORDER BY c.ordinal_position ASC
+      `,
+      [schemaName, resolvedTableName]
+    )
+  );
+  if (columnRows.length < 1) {
+    throw new Error(`Could not introspect table "${resolvedTableName}" in schema "${schemaName}".`);
+  }
+
+  const primaryRows = normalizeRows(
+    await knex.raw(
+      `
+        SELECT
+          k.column_name AS columnName,
+          k.ordinal_position AS ordinalPosition
+        FROM information_schema.table_constraints t
+        JOIN information_schema.key_column_usage k
+          ON k.constraint_name = t.constraint_name
+         AND k.table_schema = t.table_schema
+         AND k.table_name = t.table_name
+        WHERE t.table_schema = ?
+          AND t.table_name = ?
+          AND t.constraint_type = 'PRIMARY KEY'
+        ORDER BY k.ordinal_position ASC
+      `,
+      [schemaName, resolvedTableName]
+    )
+  );
+
+  const indexRows = normalizeRows(
+    await knex.raw(
+      `
+        SELECT
+          s.index_name AS indexName,
+          s.non_unique AS nonUnique,
+          s.column_name AS columnName,
+          s.seq_in_index AS seqInIndex
+        FROM information_schema.statistics s
+        WHERE s.table_schema = ?
+          AND s.table_name = ?
+          AND s.index_name <> 'PRIMARY'
+        ORDER BY s.index_name ASC, s.seq_in_index ASC
+      `,
+      [schemaName, resolvedTableName]
+    )
+  );
+
+  const columns = Object.freeze(columnRows.map((row) => normalizeColumn(row)));
+  const resolvedIdColumn = requireIdColumn(columns, idColumn);
+  const primaryKeyColumns = normalizePrimaryKeyColumns(primaryRows);
+  requirePrimaryKeyContainsId(primaryKeyColumns, resolvedIdColumn);
+
+  const snapshot = Object.freeze({
+    dialect: "mysql2",
+    schemaName,
+    tableName: resolvedTableName,
+    idColumn: resolvedIdColumn,
+    primaryKeyColumns,
+    hasWorkspaceOwnerColumn: columns.some((column) => column.name === "workspace_owner_id"),
+    hasUserOwnerColumn: columns.some((column) => column.name === "user_owner_id"),
+    columns,
+    indexes: normalizeIndexes(indexRows)
+  });
+
+  return snapshot;
+}
+
+export { introspectCrudTableSnapshot };

package/test/entrypoints.boundary.test.js

@@ -28,5 +28,6 @@ test("server provider module exports mysql service provider only", () => {
 test("shared entrypoint exports mysql dialect helpers", () => {
   assert.equal(sharedApi.DIALECT_ID, "mysql2");
   assert.equal(sharedApi.getDialectId(), "mysql2");
+  assert.equal(typeof sharedApi.introspectCrudTableSnapshot, "function");
   assert.equal(typeof sharedApi.DatabaseRuntimeMysqlServiceProvider, "undefined");
 });

package/test/introspectCrudTable.test.js

@@ -0,0 +1,265 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { introspectCrudTableSnapshot } from "../src/shared/introspectCrudTable.js";
+
+function createKnexRawDouble({
+  schemaName = "appdb",
+  columns = [],
+  primaryKeyColumns = [],
+  indexes = []
+} = {}) {
+  const calls = [];
+
+  const knex = {
+    async raw(sql, bindings = []) {
+      const normalizedSql = String(sql || "").toLowerCase();
+      calls.push({
+        sql: normalizedSql,
+        bindings: Array.isArray(bindings) ? [...bindings] : []
+      });
+
+      if (normalizedSql.includes("select database() as schemaname")) {
+        return [[{ schemaName }], []];
+      }
+      if (normalizedSql.includes("from information_schema.columns")) {
+        return [[...columns], []];
+      }
+      if (normalizedSql.includes("from information_schema.table_constraints")) {
+        return [[...primaryKeyColumns], []];
+      }
+      if (normalizedSql.includes("from information_schema.statistics")) {
+        return [[...indexes], []];
+      }
+
+      throw new Error(`Unexpected SQL in test double: ${normalizedSql}`);
+    }
+  };
+
+  return {
+    knex,
+    calls
+  };
+}
+
+test("introspectCrudTableSnapshot maps MySQL table metadata to normalized snapshot", async () => {
+  const { knex } = createKnexRawDouble({
+    columns: [
+      {
+        columnName: "id",
+        dataType: "int",
+        columnType: "int unsigned",
+        isNullable: "NO",
+        columnDefault: null,
+        extra: "auto_increment",
+        characterMaximumLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 1
+      },
+      {
+        columnName: "workspace_owner_id",
+        dataType: "int",
+        columnType: "int unsigned",
+        isNullable: "YES",
+        columnDefault: "NULL",
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 2
+      },
+      {
+        columnName: "user_owner_id",
+        dataType: "int",
+        columnType: "int unsigned",
+        isNullable: "YES",
+        columnDefault: "NULL",
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 3
+      },
+      {
+        columnName: "first_name",
+        dataType: "varchar",
+        columnType: "varchar(160)",
+        isNullable: "NO",
+        columnDefault: null,
+        extra: "",
+        characterMaximumLength: 160,
+        numericPrecision: null,
+        numericScale: null,
+        datetimePrecision: null,
+        ordinalPosition: 4
+      },
+      {
+        columnName: "vip",
+        dataType: "tinyint",
+        columnType: "tinyint(1)",
+        isNullable: "NO",
+        columnDefault: "0",
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: 3,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 5
+      },
+      {
+        columnName: "contact_tier",
+        dataType: "enum",
+        columnType: "enum('VIP','New')",
+        isNullable: "NO",
+        columnDefault: "VIP",
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: null,
+        numericScale: null,
+        datetimePrecision: null,
+        ordinalPosition: 6
+      },
+      {
+        columnName: "updated_at",
+        dataType: "datetime",
+        columnType: "datetime",
+        isNullable: "NO",
+        columnDefault: "CURRENT_TIMESTAMP",
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: null,
+        numericScale: null,
+        datetimePrecision: 0,
+        ordinalPosition: 7
+      }
+    ],
+    primaryKeyColumns: [{ columnName: "id" }],
+    indexes: [
+      {
+        indexName: "idx_contacts_first_name",
+        nonUnique: 1,
+        columnName: "first_name",
+        seqInIndex: 1
+      },
+      {
+        indexName: "uq_contacts_vip",
+        nonUnique: 0,
+        columnName: "vip",
+        seqInIndex: 1
+      }
+    ]
+  });
+
+  const snapshot = await introspectCrudTableSnapshot(knex, {
+    tableName: "contacts",
+    idColumn: "id"
+  });
+
+  assert.equal(snapshot.dialect, "mysql2");
+  assert.equal(snapshot.tableName, "contacts");
+  assert.equal(snapshot.idColumn, "id");
+  assert.deepEqual(snapshot.primaryKeyColumns, ["id"]);
+  assert.equal(snapshot.hasWorkspaceOwnerColumn, true);
+  assert.equal(snapshot.hasUserOwnerColumn, true);
+
+  const firstName = snapshot.columns.find((column) => column.name === "first_name");
+  assert.ok(firstName);
+  assert.equal(firstName.key, "firstName");
+  assert.equal(firstName.typeKind, "string");
+  assert.equal(firstName.maxLength, 160);
+
+  const workspaceOwnerId = snapshot.columns.find((column) => column.name === "workspace_owner_id");
+  assert.ok(workspaceOwnerId);
+  assert.equal(workspaceOwnerId.hasDefault, false);
+
+  const vip = snapshot.columns.find((column) => column.name === "vip");
+  assert.ok(vip);
+  assert.equal(vip.typeKind, "boolean");
+  assert.equal(vip.hasDefault, true);
+
+  const contactTier = snapshot.columns.find((column) => column.name === "contact_tier");
+  assert.ok(contactTier);
+  assert.deepEqual(contactTier.enumValues, ["VIP", "New"]);
+
+  assert.deepEqual(snapshot.indexes, [
+    {
+      name: "idx_contacts_first_name",
+      unique: false,
+      columns: ["first_name"]
+    },
+    {
+      name: "uq_contacts_vip",
+      unique: true,
+      columns: ["vip"]
+    }
+  ]);
+});
+
+test("introspectCrudTableSnapshot rejects unsupported column types", async () => {
+  const { knex } = createKnexRawDouble({
+    columns: [
+      {
+        columnName: "id",
+        dataType: "int",
+        columnType: "int unsigned",
+        isNullable: "NO",
+        columnDefault: null,
+        extra: "auto_increment",
+        characterMaximumLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 1
+      },
+      {
+        columnName: "location",
+        dataType: "point",
+        columnType: "point",
+        isNullable: "YES",
+        columnDefault: null,
+        extra: "",
+        characterMaximumLength: null,
+        numericPrecision: null,
+        numericScale: null,
+        datetimePrecision: null,
+        ordinalPosition: 2
+      }
+    ],
+    primaryKeyColumns: [{ columnName: "id" }]
+  });
+
+  await assert.rejects(
+    () => introspectCrudTableSnapshot(knex, { tableName: "contacts" }),
+    /Unsupported MySQL column type "point"/
+  );
+});
+
+test("introspectCrudTableSnapshot rejects when primary key does not include id column", async () => {
+  const { knex } = createKnexRawDouble({
+    columns: [
+      {
+        columnName: "id",
+        dataType: "int",
+        columnType: "int unsigned",
+        isNullable: "NO",
+        columnDefault: null,
+        extra: "auto_increment",
+        characterMaximumLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        datetimePrecision: null,
+        ordinalPosition: 1
+      }
+    ],
+    primaryKeyColumns: [{ columnName: "other_id" }]
+  });
+
+  await assert.rejects(
+    () => introspectCrudTableSnapshot(knex, { tableName: "contacts" }),
+    /Primary key must include id column "id"/
+  );
+});