@jskit-ai/agent-docs 0.1.15 → 0.1.16

package/guide/agent/generators/advanced-cruds.md

@@ -847,6 +847,8 @@ In JSKIT CRUD:
 Use these rules:
 
 - for explicit DB column overrides, use `repository.column`
+- standard writable `date-time` fields are serialized automatically during CRUD writes
+- use `repository.writeSerializer` only for non-default DB write serialization
 - for computed output fields, use `repository.storage: "virtual"`
 - do not put computed fields in create/patch write schemas
 
@@ -892,6 +894,8 @@ Once registered there:
 - generic CRUD `listByIds`
 - generic CRUD `listByForeignIds`
 
+and generic CRUD writes automatically serialize standard writable `date-time` fields during create/update payload mapping, so normal datetime DB formatting does not need per-field metadata or repository-specific `preparePayload` hooks. Keep `repository.writeSerializer` for non-default cases only.
+
 all pick up the projection automatically, so you should not hand-patch `clearSelect()` / re-select logic into each method.
 
 Important limits:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/INDEX.md

@@ -28,7 +28,7 @@ How to use it:
   - `ui-testing.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`
-- fieldMeta, `repository.column`, computed field, virtual field, projection, `createCrudResourceRuntime`, `remainingBatchWeight`
+- fieldMeta, `repository.column`, `repository.writeSerializer`, computed field, virtual field, projection, `createCrudResourceRuntime`, `remainingBatchWeight`, datetime write serialization
   - `crud-repository-mapping.md`
 
 ## Current Patterns

package/patterns/crud-repository-mapping.md

@@ -9,9 +9,11 @@ Default JSKIT pattern:
 1. Treat the schema as the API contract only.
 2. Put persistence mapping in `resource.fieldMeta`.
 3. Use `repository.column` for explicit DB column overrides.
-4. Use `repository.storage: "virtual"` for computed output fields.
-5. Register computed SQL projections once in the repository runtime with `virtualFields`.
-6. Let generic CRUD read paths apply those projections automatically.
+4. Let generic CRUD runtime handle standard writable `date-time` fields automatically at the DB write seam.
+5. Use `repository.writeSerializer` only for non-default write serialization.
+6. Use `repository.storage: "virtual"` for computed output fields.
+7. Register computed SQL projections once in the repository runtime with `virtualFields`.
+8. Let generic CRUD read paths apply those projections automatically.
 
 Field meta rules:
 - for a normal override, write:
@@ -36,14 +38,29 @@ RESOURCE_FIELD_META.push({
 });
 ```
 
+- for a non-default write serializer override, write:
+
+```js
+RESOURCE_FIELD_META.push({
+  key: "arrivalDatetime",
+  repository: {
+    writeSerializer: "datetime-utc"
+  }
+});
+```
+
 - omit `repository` entirely when the field is column-backed and the default snake_case mapping is correct
+- standard writable `format: "date-time"` fields do not need explicit `repository.writeSerializer`
+- use `repository.writeSerializer` only for non-default DB write behavior; keep `bodyValidator.normalize(...)` in API shape
 - `repository.storage: "virtual"` cannot also define `repository.column`
+- `repository.storage: "virtual"` cannot also define `repository.writeSerializer`
 - `repository.storage: "virtual"` fields must not appear in create/patch write schemas
 
 Repository pattern:
 - build the runtime with `createCrudResourceRuntime(resource, { ... })`
 - register computed projections in `virtualFields`
 - keep SQL in the repository, not in shared metadata
+- let generic CRUD runtime apply `repository.writeSerializer` during create/update writes
 
 Example:
 
@@ -64,6 +81,8 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 
 What CRUD core now does for you:
 - default select columns include only column-backed output fields
+- create/update write payloads serialize standard writable `date-time` fields centrally
+- create/update write payloads also apply any explicit field write serializers centrally
 - `list`, `findById`, `listByIds`, and `listByForeignIds` apply registered virtual projections automatically
 - search and parent-filter fallback derivation only use column-backed fields
 - `listByIds(..., { valueKey })` requires that `valueKey` be column-backed
@@ -76,6 +95,8 @@ Avoid:
 Review checks:
 - schema defines contract, not storage
 - `fieldMeta.repository` owns mapping
+- standard datetime DB write serialization stays automatic and runtime-owned
+- any non-default DB write serialization lives in `repository.writeSerializer`, not in per-repository hooks
 - computed fields use `repository.storage: "virtual"`
 - repository runtime registers matching `virtualFields`
 - no per-method projection duplication when generic CRUD reads already cover the field

package/reference/autogen/packages/crud-core.md

@@ -211,7 +211,7 @@ Exports
 - `deriveRepositoryMappingFromResource(resource = {}, { context = "crudRepository" } = {})`
 - `applyCrudListQueryFilters(query, { idColumn = "id", cursor = "", applyCursor = true, q = "", searchColumns = [], parentFilters = {}, parentFilterColumns = {} } = {})`
 - `mapRecordRow(row, fieldKeys = [], overrides = {}, { recordIdKeys = [] } = {})`
-- `buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {})`
+- `buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {}, { serializerByKey = {} } = {})`
 - `resolveColumnName(fieldKey, overrides = {})`
 - `resolveCrudIdColumn(idColumn, { fallback = "id" } = {})`
 - `buildRepositoryColumnMetadata({ outputKeys = [], writeKeys = [], columnOverrides = {}, fieldStorageByKey = {} } = {})`
@@ -220,6 +220,7 @@ Local functions
 - `requireObjectSchemaProperties(schema, { context = "crudRepository", schemaLabel = "schema" } = {})`
 - `normalizeResourceFieldMetaEntries(fieldMeta = [])`
 - `schemaIncludesStringType(schema = {})`
+- `schemaIncludesDateTimeFormat(schema = {})`
 - `schemaIncludesRecordIdType(schema = {})`
 
 ### `src/server/resourceRuntime/index.js`
@@ -317,12 +318,14 @@ Local functions
 Exports
 - `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(value, { context = "crud fieldMeta ui.formControl", defaultValue = CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE } = {})`
 - `isCrudRuntimeOutputOnlyFieldKey(value = "", { lookupContainerKey = CRUD_RUNTIME_LOOKUPS_FIELD_KEY } = {})`
 - `normalizeCrudFieldRepositoryConfig(fieldMetaEntry = {}, { context = "crud fieldMeta repository", fieldKey = "" } = {})`
+- `normalizeCrudFieldRepositoryWriteSerializer(value, { context = "crud fieldMeta repository", fieldKey = "" } = {})`
 
 ### `src/shared/crudNamespaceSupport.js`
 Exports

package/reference/autogen/packages/crud-server-generator.md

@@ -215,6 +215,39 @@ Exports
 Exports
 - None
 
+### .tmp-crud-server-template-fixture-FNbPfi
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/actionIds.js`
+Exports
+- `actionIds`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/actions.js`
+Exports
+- `createActions({ surface = "" } = {})`
+Local functions
+- `requireActionSurface(surface = "")`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/listConfig.js`
+Exports
+- `LIST_CONFIG`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/registerRoutes.js`
+Exports
+- `registerRoutes(app, { routeOwnershipFilter = "public", routeSurface = "", routeRelativePath = "" } = {})`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/repository.js`
+Exports
+- `createRepository(knex, options = {})`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/server/service.js`
+Exports
+- `createService({ customersRepository, fieldAccess = DEFAULT_FIELD_ACCESS } = {})`
+- `serviceEvents`
+
+### `.tmp-crud-server-template-fixture-FNbPfi/src/shared/customerResource.js`
+Exports
+- `resource`
+
 ### test-support
 
 ### `test-support/templateServerFixture.js`