@jskit-ai/json-rest-api-core 0.1.90 → 0.1.92

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/json-rest-api-core",
-  version: "0.1.90",
+  version: "0.1.92",
   kind: "runtime",
   description: "Shared internal json-rest-api host runtime with autofilter, query-projection, and row-policy support.",
   dependsOn: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/json-rest-api-core",
-  "version": "0.1.90",
+  "version": "0.1.92",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -11,6 +11,6 @@
   "dependencies": {
     "hooked-api": "1.x.x",
     "json-rest-api": "^1.0.27",
-    "@jskit-ai/kernel": "0.1.146"
+    "@jskit-ai/kernel": "0.1.147"
   }
 }

package/src/server/jsonRestApiHost.js

@@ -53,6 +53,9 @@ const JSON_REST_RESERVED_QUERY_KEYS = Object.freeze(new Set([
   "sort",
   "fields"
 ]));
+const JSON_REST_CALENDAR_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const JSON_REST_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u;
+const JSON_REST_DATABASE_UTC_DATE_TIME_PATTERN = /^(\d{4}-\d{2}-\d{2}) ((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?)$/u;
 
 function isPlainJsonRestObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -105,6 +108,132 @@ function cloneJsonRestResourceValue(value, { writeSerializers = {} } = {}) {
   return next;
 }
 
+function resolveCanonicalCalendarDate(value) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime())
+      ? ""
+      : value.toISOString().slice(0, 10);
+  }
+
+  const normalized = typeof value === "string" ? value.trim() : "";
+  const candidate = normalized.match(/^(\d{4}-\d{2}-\d{2})(?:$|T)/u)?.[1] || "";
+  if (!JSON_REST_CALENDAR_DATE_PATTERN.test(candidate)) {
+    return "";
+  }
+
+  const parsed = new Date(`${candidate}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== candidate) {
+    return "";
+  }
+
+  return candidate;
+}
+
+function serializeJsonRestCalendarDate(value) {
+  if (value == null) {
+    return value;
+  }
+
+  const canonical = resolveCanonicalCalendarDate(value);
+  if (!canonical) {
+    throw new TypeError("json-rest-api calendar date must be a valid YYYY-MM-DD value.");
+  }
+  return canonical;
+}
+
+function resolveCanonicalDateTime(value) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "" : value.toISOString();
+  }
+
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (JSON_REST_DATE_TIME_PATTERN.test(normalized)) {
+    return normalized;
+  }
+
+  const databaseMatch = JSON_REST_DATABASE_UTC_DATE_TIME_PATTERN.exec(normalized);
+  return databaseMatch ? `${databaseMatch[1]}T${databaseMatch[2]}Z` : "";
+}
+
+function applyJsonRestCalendarDateWriteSerializers(scopeOptions = {}) {
+  const schema = normalizeJsonRestObject(scopeOptions.schema);
+  for (const fieldDefinition of Object.values(schema)) {
+    if (normalizeJsonRestText(fieldDefinition?.type).toLowerCase() !== "date") {
+      continue;
+    }
+    if (fieldDefinition?.virtual === true || fieldDefinition?.storage?.virtual === true) {
+      continue;
+    }
+
+    const storage = normalizeJsonRestObject(fieldDefinition.storage);
+    if (typeof storage.serialize === "function") {
+      continue;
+    }
+    fieldDefinition.storage = {
+      ...storage,
+      serialize: serializeJsonRestCalendarDate
+    };
+  }
+}
+
+function normalizeJsonRestTemporalEntry(entry = null, scopes = {}) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return entry;
+  }
+
+  const schema = normalizeJsonRestObject(
+    scopes?.[normalizeJsonRestText(entry.type)]?.vars?.schemaInfo?.schemaStructure
+  );
+  const attributes = normalizeJsonRestObject(entry.attributes);
+  for (const [fieldName, definition] of Object.entries(schema)) {
+    if (!Object.hasOwn(attributes, fieldName) || attributes[fieldName] == null) {
+      continue;
+    }
+
+    const fieldType = normalizeJsonRestText(definition?.type).toLowerCase();
+    const canonical = fieldType === "date"
+      ? resolveCanonicalCalendarDate(attributes[fieldName])
+      : fieldType === "datetime"
+        ? resolveCanonicalDateTime(attributes[fieldName])
+        : "";
+    if (canonical) {
+      attributes[fieldName] = canonical;
+    }
+  }
+
+  return entry;
+}
+
+function normalizeJsonRestTemporalDocument(document = null, scopes = {}) {
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    return document;
+  }
+
+  const data = Array.isArray(document.data) ? document.data : [document.data];
+  for (const entry of data) {
+    normalizeJsonRestTemporalEntry(entry, scopes);
+  }
+  for (const entry of Array.isArray(document.included) ? document.included : []) {
+    normalizeJsonRestTemporalEntry(entry, scopes);
+  }
+  return document;
+}
+
+const JsonRestTemporalPlugin = Object.freeze({
+  name: "jskit-temporal",
+  dependencies: ["rest-api"],
+  install({ addHook, scopes }) {
+    addHook("finish", "normalizeCalendarDateDocuments", {}, ({ context }) => {
+      if (context?.record) {
+        normalizeJsonRestTemporalDocument(context.record, scopes);
+      }
+      if (context?.responseRecord) {
+        normalizeJsonRestTemporalDocument(context.responseRecord, scopes);
+      }
+    });
+  }
+});
+
 async function addResourceIfMissing(api, scopeName, resourceConfig) {
   if (api?.resources?.[scopeName]) {
     return api.resources[scopeName];
@@ -548,6 +677,7 @@ function createJsonRestResourceScopeOptions(
   const scopeOptions = cloneJsonRestResourceValue(resource, {
     writeSerializers: normalizeJsonRestObject(writeSerializers)
   });
+  applyJsonRestCalendarDateWriteSerializers(scopeOptions);
   if (isPlainJsonRestObject(searchSchema)) {
     scopeOptions.searchSchema = {
       ...normalizeJsonRestObject(scopeOptions.searchSchema),
@@ -702,6 +832,7 @@ async function createJsonRestApiHost({ knex }) {
     },
     presets: JSON_REST_AUTOFILTER_PRESETS
   });
+  await api.use(JsonRestTemporalPlugin);
 
   return api;
 }

package/test/entrypoints.boundary.test.js

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import test from "node:test";
 import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
@@ -363,6 +364,14 @@ test("createJsonRestResourceScopeOptions clones canonical resource metadata and
           })
         })
       }),
+      publishedOn: Object.freeze({
+        type: "date",
+        operations: Object.freeze({
+          output: Object.freeze({
+            required: true
+          })
+        })
+      }),
       bookingSteps: Object.freeze({
         type: "array",
         storage: Object.freeze({
@@ -417,6 +426,16 @@ test("createJsonRestResourceScopeOptions clones canonical resource metadata and
   assert.equal(result.schema.createdAt.storage.serialize, serializer);
   assert.equal(result.schema.createdAt.storage.serialize(null), null);
   assert.equal(result.schema.createdAt.storage.writeSerializer, undefined);
+  assert.equal(
+    result.schema.publishedOn.storage.serialize(new Date("2024-02-29T00:00:00.000Z")),
+    "2024-02-29"
+  );
+  assert.equal(result.schema.publishedOn.storage.serialize("2024-02-29"), "2024-02-29");
+  assert.equal(result.schema.publishedOn.storage.serialize(null), null);
+  assert.throws(
+    () => result.schema.publishedOn.storage.serialize("2023-02-29"),
+    /valid YYYY-MM-DD/
+  );
   assert.equal(result.schema.bookingSteps.virtual, true);
   assert.equal(result.schema.pets.virtual, true);
   assert.equal(result.normalizeId, normalizeId);
@@ -622,6 +641,166 @@ test("createJsonRestApiHost installs json-rest-api query projections", async ()
   assert.equal(typeof api.resources.projectionContacts.vars.queryFields.displayName.select, "function");
 });
 
+test("createJsonRestApiHost returns JSON-native temporal values from database records", async () => {
+  const fakeKnex = Object.assign(() => {}, {
+    client: {
+      config: {
+        client: "sqlite3"
+      }
+    },
+    async raw() {
+      return [{ version: "3.35.5" }];
+    },
+    transaction() {}
+  });
+  const api = await createJsonRestApiHost({ knex: fakeKnex });
+
+  await api.addResource("books", createJsonRestResourceScopeOptions({
+    tableName: "books",
+    schema: {
+      id: { type: "id", primary: true },
+      publishedOn: { type: "date" },
+      scheduledAt: { type: "dateTime" },
+      opensAt: { type: "time" }
+    }
+  }));
+  await api.addResource("holidays", createJsonRestResourceScopeOptions({
+    tableName: "holidays",
+    schema: {
+      id: { type: "id", primary: true },
+      observedOn: { type: "date" }
+    }
+  }));
+
+  const scheduledAt = new Date("2024-02-29T12:34:56.000Z");
+  const record = {
+    data: {
+      type: "books",
+      id: "1",
+      attributes: {
+        publishedOn: new Date("2024-02-29T00:00:00.000Z"),
+        scheduledAt,
+        opensAt: "09:45:00"
+      }
+    },
+    included: [{
+      type: "holidays",
+      id: "7",
+      attributes: {
+        observedOn: new Date("2024-03-01T00:00:00.000Z")
+      }
+    }]
+  };
+
+  await api.runHooks("finish", {
+    record
+  });
+
+  assert.equal(record.data.attributes.publishedOn, "2024-02-29");
+  assert.equal(record.data.attributes.scheduledAt, "2024-02-29T12:34:56.000Z");
+  assert.equal(record.data.attributes.opensAt, "09:45:00");
+  assert.equal(record.included[0].attributes.observedOn, "2024-03-01");
+});
+
+test("calendar date writes and responses keep leap day across server time zones", () => {
+  const hostModuleUrl = new URL(
+    "../src/server/jsonRestApiHost.js",
+    import.meta.url
+  ).href;
+  const script = `
+    import {
+      createJsonRestApiHost,
+      createJsonRestResourceScopeOptions
+    } from ${JSON.stringify(hostModuleUrl)};
+    const fakeKnex = Object.assign(() => {}, {
+      client: { config: { client: "sqlite3" } },
+      async raw() { return [{ version: "3.35.5" }]; },
+      transaction() {}
+    });
+    const api = await createJsonRestApiHost({ knex: fakeKnex });
+    const scopeOptions = createJsonRestResourceScopeOptions({
+      tableName: "books",
+      schema: {
+        id: { type: "id", primary: true },
+        publishedOn: { type: "date" },
+        scheduledAt: { type: "dateTime" },
+        opensAt: { type: "time" }
+      }
+    });
+    await api.addResource("books", scopeOptions);
+    const record = {
+      data: {
+        type: "books",
+        id: "1",
+        attributes: {
+          publishedOn: new Date("2024-02-29T00:00:00.000Z"),
+          scheduledAt: new Date("2024-02-29T12:34:56.000Z"),
+          opensAt: "09:45:00"
+        }
+      }
+    };
+    await api.runHooks("finish", { record });
+    process.stdout.write(JSON.stringify({
+      write: scopeOptions.schema.publishedOn.storage.serialize(
+        new Date("2024-02-29T00:00:00.000Z")
+      ),
+      publishedOn: record.data.attributes.publishedOn,
+      scheduledAt: record.data.attributes.scheduledAt,
+      opensAt: record.data.attributes.opensAt
+    }));
+  `;
+
+  for (const timezone of ["UTC", "Australia/Perth", "America/Los_Angeles", "Pacific/Kiritimati"]) {
+    const result = spawnSync(process.execPath, ["--input-type=module", "--eval", script], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        TZ: timezone
+      }
+    });
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      write: "2024-02-29",
+      publishedOn: "2024-02-29",
+      scheduledAt: "2024-02-29T12:34:56.000Z",
+      opensAt: "09:45:00"
+    }, timezone);
+  }
+});
+
+test("createJsonRestApiHost maps UTC database datetimes to RFC 3339 strings", async () => {
+  const fakeKnex = Object.assign(() => {}, {
+    client: { config: { client: "sqlite3" } },
+    async raw() {
+      return [{ version: "3.35.5" }];
+    },
+    transaction() {}
+  });
+  const api = await createJsonRestApiHost({ knex: fakeKnex });
+
+  await api.addResource("jobs", createJsonRestResourceScopeOptions({
+    tableName: "jobs",
+    schema: {
+      id: { type: "id", primary: true },
+      scheduledAt: { type: "dateTime" }
+    }
+  }));
+  const record = {
+    data: {
+      type: "jobs",
+      id: "1",
+      attributes: {
+        scheduledAt: "2024-02-29 12:34:56.123"
+      }
+    }
+  };
+
+  await api.runHooks("finish", { record });
+
+  assert.equal(record.data.attributes.scheduledAt, "2024-02-29T12:34:56.123Z");
+});
+
 test("returnNullWhenJsonRestResourceMissing only swallows missing-resource errors", async () => {
   await assert.doesNotReject(async () => {
     const result = await returnNullWhenJsonRestResourceMissing(async () => {