@jskit-ai/crud-core 0.1.62 → 0.1.63

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.62",
+  version: "0.1.63",
   kind: "runtime",
   description: "Shared CRUD helpers used by CRUD modules.",
   dependsOn: [
@@ -26,7 +26,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/crud-core": "0.1.62"
+        "@jskit-ai/crud-core": "0.1.63"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -26,12 +26,12 @@
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/database-runtime": "0.1.54",
-    "@jskit-ai/kernel": "0.1.54",
-    "@jskit-ai/realtime": "0.1.53",
-    "@jskit-ai/shell-web": "0.1.53",
-    "@jskit-ai/users-core": "0.1.64",
-    "@jskit-ai/users-web": "0.1.69",
+    "@jskit-ai/database-runtime": "0.1.55",
+    "@jskit-ai/kernel": "0.1.55",
+    "@jskit-ai/realtime": "0.1.54",
+    "@jskit-ai/shell-web": "0.1.54",
+    "@jskit-ai/users-core": "0.1.65",
+    "@jskit-ai/users-web": "0.1.70",
     "typebox": "^1.0.81"
   }
 }

package/src/server/repositorySupport.js

@@ -1,4 +1,7 @@
-import { normalizeDbRecordId } from "@jskit-ai/database-runtime/shared";
+import {
+  normalizeDbRecordId,
+  toDatabaseDateTimeUtc
+} from "@jskit-ai/database-runtime/shared";
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
 import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
@@ -10,6 +13,7 @@ import {
 } from "@jskit-ai/kernel/shared/support/crudLookup";
 import {
   CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
+  CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC,
   CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL,
   isCrudRuntimeOutputOnlyFieldKey,
   normalizeCrudFieldRepositoryConfig
@@ -17,6 +21,9 @@ import {
 
 const DEFAULT_LIST_LIMIT = 20;
 const MAX_LIST_LIMIT = 100;
+const CRUD_WRITE_SERIALIZERS = Object.freeze({
+  [CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC]: (value) => toDatabaseDateTimeUtc(value)
+});
 
 function normalizeCrudListCursor(cursor = null, { allowEmpty = true } = {}) {
   if (cursor === undefined || cursor === null) {
@@ -170,6 +177,23 @@ function schemaIncludesStringType(schema = {}) {
   return variants.some((entry) => schemaIncludesStringType(entry));
 }
 
+function schemaIncludesDateTimeFormat(schema = {}) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return false;
+  }
+
+  if (normalizeText(schema.format).toLowerCase() === "date-time") {
+    return true;
+  }
+
+  const variants = Array.isArray(schema.anyOf)
+    ? schema.anyOf
+    : Array.isArray(schema.oneOf)
+      ? schema.oneOf
+      : [];
+  return variants.some((entry) => schemaIncludesDateTimeFormat(entry));
+}
+
 function schemaIncludesRecordIdType(schema = {}) {
   if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
     return false;
@@ -233,6 +257,7 @@ function deriveRepositoryMappingFromResource(resource = {}, { context = "crudRep
 
   const fieldStorageByKey = {};
   const columnOverrides = {};
+  const writeSerializerByKey = {};
   for (const entry of normalizeResourceFieldMetaEntries(resource.fieldMeta)) {
     const key = normalizeText(entry.key);
     if (!key) {
@@ -246,6 +271,9 @@ function deriveRepositoryMappingFromResource(resource = {}, { context = "crudRep
     if (repositoryConfig.column) {
       columnOverrides[key] = repositoryConfig.column;
     }
+    if (repositoryConfig.writeSerializer) {
+      writeSerializerByKey[key] = repositoryConfig.writeSerializer;
+    }
   }
 
   for (const key of [...outputKeys, ...writeKeys]) {
@@ -313,9 +341,27 @@ function deriveRepositoryMappingFromResource(resource = {}, { context = "crudRep
     }
   }
 
+  for (const key of writeKeys) {
+    if ((fieldStorageByKey[key] || CRUD_FIELD_REPOSITORY_STORAGE_COLUMN) !== CRUD_FIELD_REPOSITORY_STORAGE_COLUMN) {
+      continue;
+    }
+
+    if (writeSerializerByKey[key]) {
+      continue;
+    }
+
+    const schema = writeProperties[key] || patchProperties[key];
+    if (!schemaIncludesDateTimeFormat(schema)) {
+      continue;
+    }
+
+    writeSerializerByKey[key] = CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC;
+  }
+
   return Object.freeze({
     outputKeys,
     writeKeys,
+    writeSerializerByKey: Object.freeze(writeSerializerByKey),
     fieldStorageByKey: Object.freeze(fieldStorageByKey),
     columnOverrides: Object.freeze(columnOverrides),
     columnBackedOutputKeys: Object.freeze(columnBackedOutputKeys),
@@ -431,8 +477,11 @@ function applyCrudListQueryFilters(
   return nextQuery;
 }
 
-function buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {}) {
+function buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {}, { serializerByKey = {} } = {}) {
   const source = normalizeObjectInput(sourcePayload);
+  const normalizedSerializerByKey = serializerByKey && typeof serializerByKey === "object" && !Array.isArray(serializerByKey)
+    ? serializerByKey
+    : {};
   const payload = {};
   for (const key of fieldKeys) {
     const normalizedKey = String(key || "").trim();
@@ -443,7 +492,19 @@ function buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {}) {
     if (!Object.hasOwn(source, normalizedKey)) {
       continue;
     }
-    payload[columnName] = source[normalizedKey];
+    const value = source[normalizedKey];
+    const serializerId = normalizeText(normalizedSerializerByKey[normalizedKey]).toLowerCase();
+    if (value === null || value === undefined || !serializerId) {
+      payload[columnName] = value;
+      continue;
+    }
+
+    const serializer = CRUD_WRITE_SERIALIZERS[serializerId];
+    if (typeof serializer !== "function") {
+      throw new Error(`crudRepository write serializer "${serializerId}" is not supported.`);
+    }
+
+    payload[columnName] = serializer(value);
   }
   return payload;
 }

package/src/server/resourceRuntime/index.js

@@ -1186,7 +1186,14 @@ async function createRecord(runtime, knex, payload = {}, callOptions = {}) {
     }
   );
 
-  let insertPayload = buildWritePayload(sourcePayload, runtime.mapping.writeKeys, runtime.mapping.columnOverrides);
+  let insertPayload = buildWritePayload(
+    sourcePayload,
+    runtime.mapping.writeKeys,
+    runtime.mapping.columnOverrides,
+    {
+      serializerByKey: runtime.mapping.writeSerializerByKey
+    }
+  );
   const timestamp = toInsertDateTime();
   if (runtime.defaults.createdAtColumn && !Object.hasOwn(insertPayload, runtime.defaults.createdAtColumn)) {
     insertPayload[runtime.defaults.createdAtColumn] = timestamp;
@@ -1276,7 +1283,14 @@ async function updateRecordById(runtime, knex, recordId, patch = {}, callOptions
       stageKey: "operations.updateById.preparePatch"
     }
   );
-  const dbPatch = buildWritePayload(sourcePatch, runtime.mapping.writeKeys, runtime.mapping.columnOverrides);
+  const dbPatch = buildWritePayload(
+    sourcePatch,
+    runtime.mapping.writeKeys,
+    runtime.mapping.columnOverrides,
+    {
+      serializerByKey: runtime.mapping.writeSerializerByKey
+    }
+  );
 
   if (runtime.defaults.updatedAtColumn) {
     dbPatch[runtime.defaults.updatedAtColumn] = toInsertDateTime();

package/src/shared/crudFieldMetaSupport.js

@@ -9,6 +9,30 @@ const CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE = "autocomplete";
 const CRUD_LOOKUP_FORM_CONTROL_SELECT = "select";
 const CRUD_FIELD_REPOSITORY_STORAGE_COLUMN = "column";
 const CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL = "virtual";
+const CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC = "datetime-utc";
+
+function normalizeCrudFieldRepositoryWriteSerializer(
+  value,
+  {
+    context = "crud fieldMeta repository",
+    fieldKey = ""
+  } = {}
+) {
+  const normalizedFieldKey = normalizeText(fieldKey);
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue) {
+    return "";
+  }
+
+  if (normalizedValue === CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC) {
+    return normalizedValue;
+  }
+
+  throw new Error(
+    `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.writeSerializer must be ` +
+      `"${CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC}" when provided.`
+  );
+}
 
 function checkCrudLookupFormControl(
   value,
@@ -70,7 +94,7 @@ function normalizeCrudFieldRepositoryConfig(
 
   const repositoryKeys = Object.keys(repository);
   for (const repositoryKey of repositoryKeys) {
-    if (repositoryKey !== "column" && repositoryKey !== "storage") {
+    if (repositoryKey !== "column" && repositoryKey !== "storage" && repositoryKey !== "writeSerializer") {
       throw new Error(
         `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} does not support repository.${repositoryKey}.`
       );
@@ -79,10 +103,14 @@ function normalizeCrudFieldRepositoryConfig(
 
   const column = normalizeText(repository.column);
   const storage = normalizeText(repository.storage).toLowerCase();
+  const writeSerializer = normalizeCrudFieldRepositoryWriteSerializer(repository.writeSerializer, {
+    context,
+    fieldKey: normalizedFieldKey
+  });
 
-  if (!column && !storage) {
+  if (!column && !storage && !writeSerializer) {
     throw new Error(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} requires repository.column or repository.storage.`
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} requires repository.column, repository.storage, or repository.writeSerializer.`
     );
   }
 
@@ -96,22 +124,30 @@ function normalizeCrudFieldRepositoryConfig(
       `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.storage "virtual" cannot define repository.column.`
     );
   }
+  if (storage === CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL && writeSerializer) {
+    throw new Error(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.storage "virtual" cannot define repository.writeSerializer.`
+    );
+  }
 
   return Object.freeze({
     storage: storage === CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL
       ? CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL
       : CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
-    column
+    column,
+    writeSerializer
   });
 }
 
 export {
   CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
   CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL,
+  CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC,
   CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE,
   CRUD_LOOKUP_FORM_CONTROL_SELECT,
   CRUD_RUNTIME_LOOKUPS_FIELD_KEY,
   checkCrudLookupFormControl,
   isCrudRuntimeOutputOnlyFieldKey,
-  normalizeCrudFieldRepositoryConfig
+  normalizeCrudFieldRepositoryConfig,
+  normalizeCrudFieldRepositoryWriteSerializer
 };

package/test/repositorySupport.test.js

@@ -132,6 +132,34 @@ test("buildWritePayload respects defined keys", () => {
   });
 });
 
+test("buildWritePayload serializes configured date-time keys to database shape", () => {
+  const payload = buildWritePayload(
+    {
+      scheduledAt: "2026-04-23T10:11:12.000Z",
+      archivedAt: null,
+      title: "Example"
+    },
+    ["scheduledAt", "archivedAt", "title"],
+    {
+      scheduledAt: "scheduled_at",
+      archivedAt: "archived_at",
+      title: "title"
+    },
+    {
+      serializerByKey: {
+        scheduledAt: "datetime-utc",
+        archivedAt: "datetime-utc"
+      }
+    }
+  );
+
+  assert.deepEqual(payload, {
+    scheduled_at: "2026-04-23 10:11:12.000",
+    archived_at: null,
+    title: "Example"
+  });
+});
+
 test("applyCrudListQueryFilters applies search and cursor filters", () => {
   const { query, calls } = createQueryDouble();
   const result = applyCrudListQueryFilters(query, {
@@ -565,3 +593,103 @@ test("deriveRepositoryMappingFromResource throws when create schema properties a
     /operations\.create\.bodyValidator\.schema\.properties/
   );
 });
+
+test("deriveRepositoryMappingFromResource tracks writable column-backed write serializers", () => {
+  const resource = {
+    operations: {
+      view: {
+        outputValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              id: { type: "integer" },
+              scheduledAt: { type: "string", format: "date-time" },
+              archivedAt: { type: "string", format: "date-time" },
+              remainingBatchWeight: { type: "number" }
+            }
+          }
+        }
+      },
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              scheduledAt: { type: "string", format: "date-time" }
+            }
+          }
+        }
+      },
+      patch: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              archivedAt: {
+                anyOf: [
+                  { type: "string", format: "date-time" },
+                  { type: "null" }
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "remainingBatchWeight",
+        repository: {
+          storage: "virtual"
+        }
+      }
+    ]
+  };
+
+  const mapping = deriveRepositoryMappingFromResource(resource);
+  assert.deepEqual(mapping.writeSerializerByKey, {
+    scheduledAt: "datetime-utc",
+    archivedAt: "datetime-utc"
+  });
+});
+
+test("deriveRepositoryMappingFromResource keeps explicit repository.writeSerializer metadata", () => {
+  const resource = {
+    operations: {
+      view: {
+        outputValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              id: { type: "integer" },
+              arrivalDatetime: { type: "string", format: "date-time" }
+            }
+          }
+        }
+      },
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              arrivalDatetime: { type: "string", format: "date-time" }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "arrivalDatetime",
+        repository: {
+          writeSerializer: "datetime-utc"
+        }
+      }
+    ]
+  };
+
+  const mapping = deriveRepositoryMappingFromResource(resource);
+  assert.deepEqual(mapping.writeSerializerByKey, {
+    arrivalDatetime: "datetime-utc"
+  });
+});