@jskit-ai/database-runtime 0.1.147 → 0.1.149

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/database-runtime",
-  "version": "0.1.147",
+  "version": "0.1.149",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -25,6 +25,112 @@
     "./shared/transactions": "./src/shared/transactions.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.147"
+    "@jskit-ai/kernel": "0.1.149"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "runtime.database"
+      ],
+      "requires": [
+        "runtime.database.driver"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providerEntrypoint": "src/server/providers/DatabaseRuntimeServiceProvider.js",
+        "providers": [
+          {
+            "entrypoint": "src/server/providers/DatabaseRuntimeServiceProvider.js",
+            "export": "DatabaseRuntimeServiceProvider"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server",
+            "summary": "Exports DatabaseRuntimeServiceProvider plus registerDatabaseRuntime for server container wiring."
+          },
+          {
+            "subpath": "./shared",
+            "summary": "Exports shared Knex runtime utilities (transaction manager, repository helpers, retention/json/date/dialect helpers)."
+          },
+          {
+            "subpath": "./client",
+            "summary": "Exports no runtime API today (reserved client entrypoint)."
+          }
+        ],
+        "containerTokens": {
+          "server": [
+            "runtime.database",
+            "runtime.database.driver",
+            "jskit.database.knex",
+            "jskit.database.transactionManager"
+          ],
+          "client": []
+        }
+      }
+    },
+    "ci": {
+      "environment": {},
+      "services": [],
+      "steps": [
+        {
+          "id": "database-migrations",
+          "phase": "before-verify",
+          "label": "Apply database migrations",
+          "command": "npm run db:migrate"
+        }
+      ]
+    },
+    "mutations": {
+      "dependencies": {
+        "runtime": {
+          "@jskit-ai/kernel": "0.1.149",
+          "dotenv": "^16.4.5",
+          "knex": "^3.1.0"
+        },
+        "dev": {}
+      },
+      "packageJson": {
+        "scripts": {
+          "db:migrations:sync": "jskit migrations sync",
+          "db:migrate": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:latest",
+          "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+          "db:migrate:status": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:list"
+        }
+      },
+      "procfile": {},
+      "files": [
+        {
+          "from": "templates/knexfile.js",
+          "to": "knexfile.js",
+          "reason": "Install root Knex configuration so app scripts can run migrations through Knex CLI.",
+          "category": "database-runtime",
+          "id": "database-runtime-knexfile"
+        },
+        {
+          "from": "templates/migrations/.gitkeep",
+          "to": "migrations/.gitkeep",
+          "reason": "Ensure migrations directory exists so Knex migration commands can run before any module installs migrations.",
+          "category": "database-runtime",
+          "id": "database-runtime-migrations-dir"
+        },
+        {
+          "from": "templates/migrations/constraints/.gitkeep",
+          "to": "migrations/constraints/.gitkeep",
+          "reason": "Ensure the ordered deferred-constraint migration directory exists.",
+          "category": "database-runtime",
+          "id": "database-runtime-constraint-migrations-dir"
+        }
+      ]
+    }
   }
 }

package/src/server/providers/DatabaseRuntimeServiceProvider.js

@@ -42,7 +42,7 @@ function loadKnexFactory() {
     moduleValue = symlinkSafeRequire("knex");
   } catch {
     throw new Error(
-      "Knex package is not installed. Re-run `npx jskit update package database-runtime` to apply runtime dependencies."
+      "Knex package is not installed. Run `npm install`, then `npx jskit migrations sync`."
     );
   }
 

package/src/shared/dateUtils.js

@@ -45,6 +45,155 @@ function pad(value, size = 2) {
   return String(value).padStart(size, "0");
 }
 
+function requireValidDateParts(year, month, day) {
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysByMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (
+    !Number.isInteger(year) || year < 0 || year > 9999 ||
+    !Number.isInteger(month) || month < 1 || month > 12 ||
+    !Number.isInteger(day) || day < 1 || day > daysByMonth[month - 1]
+  ) {
+    throw new TypeError("Invalid date value.");
+  }
+}
+
+function requireValidTimeParts(hours, minutes, seconds = 0) {
+  if (
+    !Number.isInteger(hours) || hours < 0 || hours > 23 ||
+    !Number.isInteger(minutes) || minutes < 0 || minutes > 59 ||
+    !Number.isInteger(seconds) || seconds < 0 || seconds > 59
+  ) {
+    throw new TypeError("Invalid time value.");
+  }
+}
+
+function parseDateParts(value) {
+  const match = String(value || "").match(/^(\d{4})-(\d{2})-(\d{2})$/u);
+  if (!match) {
+    throw new TypeError("Invalid date value.");
+  }
+  const parts = match.slice(1).map(Number);
+  requireValidDateParts(parts[0], parts[1], parts[2]);
+  return parts;
+}
+
+function normalizeTemporalPrecision(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError("Invalid temporal precision.");
+  }
+  return value;
+}
+
+function formatFraction(milliseconds, temporalPrecision) {
+  const precision = normalizeTemporalPrecision(temporalPrecision);
+  if (precision === 0) {
+    return "";
+  }
+
+  const millisecondDigits = pad(milliseconds, 3);
+  if (precision === undefined || precision === 3) {
+    return `.${millisecondDigits}`;
+  }
+  if (precision < 3) {
+    const discardedUnit = 10 ** (3 - precision);
+    if (milliseconds % discardedUnit !== 0) {
+      throw new TypeError("Temporal value exceeds configured precision.");
+    }
+    return `.${millisecondDigits.slice(0, precision)}`;
+  }
+  return `.${millisecondDigits}${"0".repeat(precision - 3)}`;
+}
+
+function requireAllowedFraction(fraction, temporalPrecision) {
+  const precision = normalizeTemporalPrecision(temporalPrecision);
+  if (precision !== undefined && fraction && fraction.length - 1 > precision) {
+    throw new TypeError("Temporal value exceeds configured precision.");
+  }
+}
+
+function toJsonDate(value) {
+  if (value == null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    const date = toDateOrThrow(value);
+    return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+  }
+
+  const normalized = String(value).trim();
+  parseDateParts(normalized);
+  return normalized;
+}
+
+function toJsonTime(value, { temporalPrecision } = {}) {
+  if (value == null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    const date = toDateOrThrow(value);
+    return [
+      `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}`,
+      formatFraction(date.getUTCMilliseconds(), temporalPrecision)
+    ].join("");
+  }
+
+  const normalized = String(value).trim();
+  const match = normalized.match(/^(\d{2}):(\d{2})(?::(\d{2})(\.\d{1,9})?)?$/u);
+  if (!match) {
+    throw new TypeError("Invalid time value.");
+  }
+  requireValidTimeParts(Number(match[1]), Number(match[2]), Number(match[3] || 0));
+  requireAllowedFraction(match[4], temporalPrecision);
+  return normalized;
+}
+
+function toJsonDateTime(value, { temporalPrecision } = {}) {
+  if (value == null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    const date = toDateOrThrow(value);
+    const year = date.getUTCFullYear();
+    if (year < 0 || year > 9999) {
+      throw new TypeError("Invalid date-time value.");
+    }
+    return [
+      `${pad(year, 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`,
+      `T${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}`,
+      formatFraction(date.getUTCMilliseconds(), temporalPrecision),
+      "Z"
+    ].join("");
+  }
+
+  const normalized = String(value).trim();
+  const match = normalized.match(
+    /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})?$/u
+  );
+  if (!match) {
+    throw new TypeError("Invalid date-time value.");
+  }
+
+  requireValidDateParts(Number(match[1]), Number(match[2]), Number(match[3]));
+  requireValidTimeParts(Number(match[4]), Number(match[5]), Number(match[6]));
+  requireAllowedFraction(match[7], temporalPrecision);
+  const offset = match[8] || "";
+  if (offset && offset !== "Z") {
+    const [offsetHours, offsetMinutes] = offset.slice(1).split(":").map(Number);
+    requireValidTimeParts(offsetHours, offsetMinutes, 0);
+  }
+
+  if (normalized.includes("T") && offset) {
+    return normalized;
+  }
+  if (offset) {
+    return `${normalized.slice(0, 10)}T${normalized.slice(11)}`;
+  }
+  return `${normalized.slice(0, 10)}T${normalized.slice(11)}Z`;
+}
+
 function toIsoString(value) {
   return toDateOrThrow(value).toISOString();
 }
@@ -83,4 +232,13 @@ function toDatabaseDateTimeUtc(value) {
   return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds}`;
 }
 
-export { normalizeDateInput, toIsoString, toInsertDateTime, toNullableDateTime, toDatabaseDateTimeUtc };
+export {
+  normalizeDateInput,
+  toIsoString,
+  toInsertDateTime,
+  toNullableDateTime,
+  toDatabaseDateTimeUtc,
+  toJsonDate,
+  toJsonTime,
+  toJsonDateTime
+};

package/src/shared/index.js

@@ -11,7 +11,10 @@ export {
   toIsoString,
   toInsertDateTime,
   toNullableDateTime,
-  toDatabaseDateTimeUtc
+  toDatabaseDateTimeUtc,
+  toJsonDate,
+  toJsonTime,
+  toJsonDateTime
 } from "./dateUtils.js";
 export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
 export { normalizeText, normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";

package/test/dateUtils.test.js

@@ -1,6 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { toIsoString, toDatabaseDateTimeUtc } from "../src/shared/dateUtils.js";
+import {
+  toIsoString,
+  toDatabaseDateTimeUtc,
+  toJsonDate,
+  toJsonTime,
+  toJsonDateTime
+} from "../src/shared/dateUtils.js";
 
 test("toIsoString normalizes valid date input", () => {
   assert.equal(toIsoString("2024-01-01T00:00:00.000Z"), "2024-01-01T00:00:00.000Z");
@@ -25,3 +31,34 @@ test("date utils throw on invalid date", () => {
   assert.throws(() => toIsoString("2024-01-01T00:00:00"), /Invalid date value\./);
   assert.throws(() => toDatabaseDateTimeUtc("not-a-date"), /Invalid date value\./);
 });
+
+test("JSON temporal serializers produce json-rest-schema 1.0.17 string shapes", () => {
+  assert.equal(toJsonDate("2026-08-13"), "2026-08-13");
+  assert.equal(toJsonDate(new Date("2026-08-13T23:59:58.123Z")), "2026-08-13");
+  assert.equal(toJsonTime("07:08"), "07:08");
+  assert.equal(toJsonTime("07:08:09.123456"), "07:08:09.123456");
+  assert.equal(toJsonTime(new Date("2026-08-13T07:08:09.000Z"), { temporalPrecision: 0 }), "07:08:09");
+  assert.equal(toJsonDateTime("2026-08-13 07:08:09.123456"), "2026-08-13T07:08:09.123456Z");
+  assert.equal(toJsonDateTime("2026-08-13T07:08:09+08:00"), "2026-08-13T07:08:09+08:00");
+  assert.equal(toJsonDateTime(new Date("2026-08-13T07:08:09.123Z")), "2026-08-13T07:08:09.123Z");
+  assert.equal(
+    toJsonDateTime(new Date("2026-08-13T07:08:09.123Z"), { temporalPrecision: 6 }),
+    "2026-08-13T07:08:09.123000Z"
+  );
+  assert.equal(toJsonDateTime(null), null);
+});
+
+test("JSON temporal serializers reject invalid or ambiguous values", () => {
+  assert.throws(() => toJsonDate("2026-02-30"), /Invalid date value/);
+  assert.throws(() => toJsonTime("25:00"), /Invalid time value/);
+  assert.throws(() => toJsonDateTime("2026-08-13T07:08"), /Invalid date-time value/);
+  assert.throws(() => toJsonDateTime("2026-08-13 07:08:09+25:00"), /Invalid time value/);
+  assert.throws(
+    () => toJsonDateTime("2026-08-13T07:08:09.123Z", { temporalPrecision: 2 }),
+    /exceeds configured precision/
+  );
+  assert.throws(
+    () => toJsonTime(new Date("2026-08-13T07:08:09.123Z"), { temporalPrecision: 2 }),
+    /exceeds configured precision/
+  );
+});

package/test/{packageDescriptor.test.js → packageMetadata.test.js}

@@ -3,14 +3,16 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
-import descriptor from "../package.descriptor.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+const packageMetadata = packageJson.jskit;
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 test("database-runtime db migrate scripts sync JSKIT-managed migrations before Knex reads them", () => {
-  const scripts = descriptor.mutations.packageJson.scripts;
+  const scripts = packageMetadata.mutations.packageJson.scripts;
 
-  assert.equal(scripts["db:migrations:sync"], "jskit migrations changed");
+  assert.equal(scripts["db:migrations:sync"], "jskit migrations sync");
   assert.equal(
     scripts["db:migrate"],
     "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:latest"
@@ -23,7 +25,7 @@ test("database-runtime db migrate scripts sync JSKIT-managed migrations before K
     scripts["db:migrate:rollback"],
     "knex --knexfile ./knexfile.js migrate:rollback"
   );
-  assert.deepEqual(descriptor.ci.steps, [
+  assert.deepEqual(packageMetadata.ci.steps, [
     {
       id: "database-migrations",
       phase: "before-verify",
@@ -35,7 +37,7 @@ test("database-runtime db migrate scripts sync JSKIT-managed migrations before K
 
 test("database-runtime runs deferred constraints after all ordinary migrations", async () => {
   const knexfile = await readFile(path.join(PACKAGE_ROOT, "templates/knexfile.js"), "utf8");
-  const deferredDirectoryMutation = descriptor.mutations.files.find(
+  const deferredDirectoryMutation = packageMetadata.mutations.files.find(
     (mutation) => mutation.id === "database-runtime-constraint-migrations-dir"
   );
 

package/package.descriptor.mjs

@@ -1,112 +0,0 @@
-export default Object.freeze({
-  packageVersion: 1,
-  packageId: "@jskit-ai/database-runtime",
-  version: "0.1.147",
-  kind: "runtime",
-  dependsOn: [
-    "@jskit-ai/kernel"
-  ],
-  capabilities: {
-    provides: [
-      "runtime.database"
-    ],
-    requires: [
-      "runtime.database.driver"
-    ]
-  },
-  runtime: {
-    server: {
-      providerEntrypoint: "src/server/providers/DatabaseRuntimeServiceProvider.js",
-      providers: [
-        {
-          entrypoint: "src/server/providers/DatabaseRuntimeServiceProvider.js",
-          export: "DatabaseRuntimeServiceProvider"
-        }
-      ]
-    },
-    client: {
-      providers: []
-    }
-  },
-  metadata: {
-    apiSummary: {
-      surfaces: [
-        {
-          subpath: "./server",
-          summary: "Exports DatabaseRuntimeServiceProvider plus registerDatabaseRuntime for server container wiring."
-        },
-        {
-          subpath: "./shared",
-          summary: "Exports shared Knex runtime utilities (transaction manager, repository helpers, retention/json/date/dialect helpers)."
-        },
-        {
-          subpath: "./client",
-          summary: "Exports no runtime API today (reserved client entrypoint)."
-        }
-      ],
-      containerTokens: {
-        server: [
-          "runtime.database",
-          "runtime.database.driver",
-          "jskit.database.knex",
-          "jskit.database.transactionManager"
-        ],
-        client: []
-      }
-    }
-  },
-  ci: {
-    environment: {},
-    services: [],
-    steps: [
-      {
-        id: "database-migrations",
-        phase: "before-verify",
-        label: "Apply database migrations",
-        command: "npm run db:migrate"
-      }
-    ]
-  },
-  mutations: {
-    dependencies: {
-      runtime: {
-        "@jskit-ai/kernel": "0.1.147",
-        "dotenv": "^16.4.5",
-        "knex": "^3.1.0"
-      },
-      dev: {}
-    },
-    packageJson: {
-      scripts: {
-        "db:migrations:sync": "jskit migrations changed",
-        "db:migrate": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:latest",
-        "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
-        "db:migrate:status": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:list"
-      }
-    },
-    procfile: {},
-    files: [
-      {
-        from: "templates/knexfile.js",
-        to: "knexfile.js",
-        reason: "Install root Knex configuration so app scripts can run migrations through Knex CLI.",
-        category: "database-runtime",
-        id: "database-runtime-knexfile"
-      },
-      {
-        from: "templates/migrations/.gitkeep",
-        to: "migrations/.gitkeep",
-        reason: "Ensure migrations directory exists so Knex migration commands can run before any module installs migrations.",
-        category: "database-runtime",
-        id: "database-runtime-migrations-dir"
-      },
-      {
-        from: "templates/migrations/constraints/.gitkeep",
-        to: "migrations/constraints/.gitkeep",
-        reason: "Ensure the ordered deferred-constraint migration directory exists.",
-        category: "database-runtime",
-        id: "database-runtime-constraint-migrations-dir"
-      }
-    ]
-  }
-});