@jarenjs/contract 0.49.2 → 0.56.0

package/README.md

@@ -51,8 +51,9 @@ published as JSON Schema in
   "$contract": "0.1",
   "id": "shop",
   "$defs": {
-    "Product": { "type": "object", "required": ["id", "name"],
-                 "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }
+    "Product": { "type": "object",
+                 "properties": { "id": { "type": "integer" }, "name": { "type": "string" } },
+                 "required": ["id", "name"] }
   },
   "operations": {
     "catalog.load": {
@@ -64,9 +65,10 @@ published as JSON Schema in
     },
     "product.save": {
       "kind": "command",
-      "input":  { "type": "object", "required": ["id", "revision", "product"], "properties": {
+      "input":  { "type": "object", "properties": {
                   "id": { "type": "integer" }, "revision": { "type": "integer" },
-                  "product": { "$ref": "#/$defs/Product" } } },
+                  "product": { "$ref": "#/$defs/Product" } },
+                  "required": ["id", "revision", "product"] },
       "output": { "$ref": "#/$defs/Product" },
       "errors": { "conflict": { "status": 409 }, "not-found": { "status": 404 } },
       "policy": { "idempotency": "required", "revision": "input:/revision" },
@@ -74,7 +76,7 @@ published as JSON Schema in
     },
     "image.bytes": {
       "kind": "read",
-      "input":  { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } },
+      "input":  { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
       "output": true,
       "http":   { "method": "GET", "path": "/api/images/{id}", "media": "application/octet-stream" }
     }
@@ -90,6 +92,51 @@ members are never coerced. An operation without `http` is bound to the
 canonical `POST /<op-id>`. A non-JSON `media` marks an operation
 *opaque*: routed and matched, never validated as JSON.
 
+## The same document, by code
+
+`@jarenjs/linq/contract` is the pen that writes this format. The
+builders are the schema pen's, every `named()` schema is hoisted into
+the contract's `$defs`, the members land in the order §12.1 fixes, and
+no default is written — so the document below is byte for byte the one
+above:
+
+```js
+import * as s from '@jarenjs/linq/schema';
+import { command, defineContract, error, http, read } from '@jarenjs/linq/contract';
+
+const Product = s.named('Product', s.object({ id: s.integer(), name: s.string() }).open());
+
+export const shop = defineContract({ id: 'shop' }, {
+  'catalog.load': read({
+    input: s.object({ since: s.string().format('date-time').optional() }).open(),
+    output: s.array(Product),
+    policy: { task: 'switch', cache: 'revision' },
+    http: http({ method: 'GET', path: '/api/catalog' }),
+  }),
+  'product.save': command({
+    input: s.object({ id: s.integer(), revision: s.integer(), product: Product }).open(),
+    output: Product,
+    errors: { conflict: error({ status: 409 }), 'not-found': error({ status: 404 }) },
+    policy: { idempotency: 'required', revision: 'input:/revision' },
+    http: http({ method: 'PUT', path: '/api/products/{id}/master' }),
+  }),
+  'image.bytes': read({
+    input: s.object({ id: s.integer() }).open(),
+    output: true,
+    http: http({ method: 'GET', path: '/api/images/{id}', media: 'application/octet-stream' }),
+  }),
+});
+
+compileContract(shop.document);                    // the same compile, the same errors
+```
+
+The types come with it, without the `types` projection: `ContractOf<typeof
+shop>` is the operation map, and `typedClient`, `typedHandlers` and
+`typedTools` carry it onto a client, a handler table and an AI toolbox.
+The pen's document is
+[CONTRACT-PEN.md](../linq/docs/CONTRACT-PEN.md); it imports nothing of
+this package.
+
 ## Compile once, use everywhere
 
 ```js
@@ -492,19 +539,19 @@ benchmark-figure gate so no number here is typed by hand:
 
 - **Route match**: the compiled matcher resolves the probe mix —
   static hot paths, variables, the static-beats-variable case, a miss —
-  at <!--bm:contract.match.vs-fmw-->172 ns per lookup vs find-my-way's 180 ns<!--/bm-->;
-  hono's TrieRouter is <!--bm:contract.match.vs-hono-->1.8x<!--/bm--> behind, and its RegExpRouter refuses this
+  at <!--fact:contract.match.vs-fmw-->172 ns per lookup vs find-my-way's 180 ns<!--/fact-->;
+  hono's TrieRouter is <!--fact:contract.match.vs-hono-->1.8x<!--/fact--> behind, and its RegExpRouter refuses this
   route table outright (a static path registered after a param sibling).
 - **Dispatch, in-process**: the whole pipeline (route, decode, validate
   input, handler, validate output,
-  serialize) is <!--bm:contract.dispatch.vs-fastify-->2.8–15.1x<!--/bm-->
+  serialize) is <!--fact:contract.dispatch.vs-fastify-->2.8–15.1x<!--/fact-->
   faster than Fastify driven through its own `inject` — a number that
   includes Fastify's mock-stream harness, which is why the next row
   exists.
 - **The honest loss**: the bare pieces Fastify composes — find-my-way +
   Ajv + fast-json-stringify, called directly with no harness and no
   response validation
-  — are <!--bm:contract.dispatch.losses-->2.4–7.5x<!--/bm--> faster than
+  — are <!--fact:contract.dispatch.losses-->2.4–7.5x<!--/fact--> faster than
   this pipeline. The wide end of that band is the bare `{ok:true}`
   route, where the rival's compiled serializer answers in ~200 ns and
   there is almost no work to amortize the pipeline against; on the
@@ -514,7 +561,7 @@ benchmark-figure gate so no number here is typed by hand:
   server kept its own contract before a byte leaves. Over a real
   loopback socket the two stacks are level: the socket dominates both.
 - **Revision**: computing it
-  costs <!--bm:contract.revision.ms-->1.4 ms<!--/bm--> for the 123-operation
+  costs <!--fact:contract.revision.ms-->1.4 ms<!--/fact--> for the 123-operation
   contract, once per process.
 
 ## What it is not

package/dist/types/project/tools.d.ts

@@ -24,7 +24,7 @@ export type ToolDefinition = {
     execute: (args: any) => any;
 };
 export type ToolClient = {
-    invoke: (op: string, input: any, ctx?: any) => any;
+    invoke(op: string, input: any, ctx?: any): any;
 };
 export type ContractToolsOptions = {
     /**

package/dist/types/project/typescript.d.ts

@@ -22,6 +22,17 @@
  * stylesheet — the D6 shapes as every binding carries them
  * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
  * are the runtime twins; a test holds the text to them).
+ *
+ * One convention rides on top of emit's reading, the suite's: a string
+ * with `format: "date-time"` or `format: "date"` is the `DateTime`
+ * brand, so a consumer's generated types agree with `@jarenjs/db`'s
+ * entity types (`entityEmitModel`) and `@jarenjs/linq`'s schema pen,
+ * which both read a date format that way. Emit itself records a format
+ * only as a dropped constraint, so the brand is applied HERE, by
+ * rewriting date-formatted string nodes to a `$ref` of one shared
+ * definition before emit reads the document — in every position, an
+ * array item as much as a member — and giving that definition the brand
+ * intersection.
  */
 export type Contract = import('../compile.js').Contract;
 export type CompiledOperation = import('../compile.js').CompiledOperation;

package/docs/CONTRACT-FORMAT.md

@@ -17,6 +17,15 @@ declared errors, a behavior policy and an HTTP binding. It is compiled
 path matcher, and it is the single source every artifact around it is
 projected from.
 
+A contract document is written by hand, or by code: `@jarenjs/linq/
+contract` is the pen that writes exactly this format — the same
+operations, schemas, policies and bindings, in §12.1's member order,
+with the operations' named schemas hoisted into `$defs` — and it types
+the client, the handler table and the AI tools from the same builders,
+without running the TypeScript projection of §12.3. The three worked
+examples below are rebuilt through it, byte for byte, by its own test
+suite.
+
 Format 0.1 covers the document, its compilation, the HTTP binding's
 *shape* (§2–§6), the HTTP **server** binding that carries it (§7–§9:
 the request pipeline and its wire errors, idempotency and the ledger
@@ -48,22 +57,22 @@ coming lines of this package and will append their sections here.
   "version": "5",
   "compat": ["4"],
   "$defs": {
+    "Catalog": {
+      "type": "object",
+      "properties": {
+        "revision": { "type": "integer" },
+        "products": { "type": "array", "items": { "$ref": "#/$defs/Product" } }
+      },
+      "required": ["revision", "products"]
+    },
     "Product": {
       "type": "object",
-      "required": ["id", "name", "price"],
       "properties": {
         "id": { "type": "integer" },
         "name": { "type": "string", "minLength": 1 },
         "price": { "type": "number", "minimum": 0 }
-      }
-    },
-    "Catalog": {
-      "type": "object",
-      "required": ["revision", "products"],
-      "properties": {
-        "revision": { "type": "integer" },
-        "products": { "type": "array", "items": { "$ref": "#/$defs/Product" } }
-      }
+      },
+      "required": ["id", "name", "price"]
     },
     "Conflict": { "type": "object", "properties": { "current": { "$ref": "#/$defs/Product" } } }
   },
@@ -81,12 +90,12 @@ coming lines of this package and will append their sections here.
       "kind": "command",
       "input": {
         "type": "object",
-        "required": ["id", "revision", "product"],
         "properties": {
           "id": { "type": "integer" },
           "revision": { "type": "integer" },
           "product": { "$ref": "#/$defs/Product" }
-        }
+        },
+        "required": ["id", "revision", "product"]
       },
       "output": { "$ref": "#/$defs/Product" },
       "errors": {
@@ -102,7 +111,7 @@ coming lines of this package and will append their sections here.
     },
     "image.bytes": {
       "kind": "read",
-      "input": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } },
+      "input": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
       "output": true,
       "http": { "method": "GET", "path": "/api/images/{id}", "media": "application/octet-stream" }
     }
@@ -427,20 +436,20 @@ The three worked examples this document is tested against, complete:
       "kind": "command",
       "input": {
         "type": "object",
-        "required": ["id", "doc"],
         "properties": {
           "id": { "type": "string" },
           "doc": { "type": "array", "items": { "type": "object" } },
           "dry": { "type": "boolean" }
-        }
+        },
+        "required": ["id", "doc"]
       },
       "output": true,
       "policy": { "idempotency": "optional" },
-      "http": { "method": "PUT", "path": "/docs/:id", "body": "doc", "in": { "dry": "query" }, "status": 204 }
+      "http": { "method": "PUT", "path": "/docs/:id", "in": { "dry": "query" }, "body": "doc", "status": 204 }
     },
     "doc.remove": {
       "kind": "command",
-      "input": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } },
+      "input": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] },
       "output": true
     }
   }
@@ -1555,6 +1564,17 @@ a test holds the text to them; `details` is `unknown` and `status`
 `number | null`, never optional members. An input-less operation's
 `input` is `null`; an opaque operation appears only in `UrlOperations`.
 
+One convention rides on top of emit's reading, and it is the suite's:
+a string with `format: "date-time"` or `format: "date"` is declared as
+`DateTime` — `string & { __jarenTag: 'date-time' }` — rendered once per
+document and referenced from every position, an array item as much as a
+member. Emit itself records a format only as a dropped constraint; the
+brand is applied by this projection so a consumer's generated types
+agree with `@jarenjs/db`'s entity types (`entityEmitModel`) and with
+`@jarenjs/linq`'s schema and contract pens, which read a date format the
+same way. A contract that already declares a `$defs` entry named
+`DateTime` keeps it; the brand takes the next free name.
+
 ### §12.4 Markdown
 
 `toMarkdown(contract, { title? })` renders one reference document: the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -102,9 +102,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/json": "^0.49.2",
-    "@jarenjs/validate": "^0.49.2",
-    "@jarenjs/emit": "^0.49.2"
+    "@jarenjs/core": "^0.56.0",
+    "@jarenjs/json": "^0.56.0",
+    "@jarenjs/validate": "^0.56.0",
+    "@jarenjs/emit": "^0.56.0"
   }
 }

package/src/project/tools.js

@@ -35,8 +35,15 @@ import { bundleSameDocument } from '../bundle.js';
 /**
  * A client as the tools read it — any binding's client. The members are
  * `any` so a client whose `invoke` narrows its own context type (the http
- * client's `InvokeContext`) still assigns.
- * @typedef {{ invoke: (op: string, input: any, ctx?: any) => any }} ToolClient
+ * client's `InvokeContext`) still assigns, and `invoke` is declared as a
+ * METHOD rather than as a function-valued property: a method's parameters
+ * are bivariant, so a client whose `invoke` narrows its OPERATION type to
+ * a literal union — `@jarenjs/linq/contract`'s `typedClient`, whose whole
+ * purpose is that narrowing — assigns here too. Under
+ * `strictFunctionTypes` the property form rejects it, and there is
+ * nothing to reject: this module only ever CALLS `invoke`, with an id it
+ * read out of the contract the client was opened on.
+ * @typedef {{ invoke(op: string, input: any, ctx?: any): any }} ToolClient
  */
 
 /**

package/src/project/typescript.js

@@ -23,6 +23,17 @@
  * stylesheet — the D6 shapes as every binding carries them
  * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
  * are the runtime twins; a test holds the text to them).
+ *
+ * One convention rides on top of emit's reading, the suite's: a string
+ * with `format: "date-time"` or `format: "date"` is the `DateTime`
+ * brand, so a consumer's generated types agree with `@jarenjs/db`'s
+ * entity types (`entityEmitModel`) and `@jarenjs/linq`'s schema pen,
+ * which both read a date format that way. Emit itself records a format
+ * only as a dropped constraint, so the brand is applied HERE, by
+ * rewriting date-formatted string nodes to a `$ref` of one shared
+ * definition before emit reads the document — in every position, an
+ * array item as much as a member — and giving that definition the brand
+ * intersection.
  */
 
 import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
@@ -66,6 +77,72 @@ function pascal(word) {
   return out;
 }
 
+/** The two formats that carry the brand. */
+const DATE_FORMATS = ['date-time', 'date'];
+
+/** The definition name the brand takes when the contract leaves it free. */
+const DATE_TIME = 'DateTime';
+
+/**
+ * Rewrite every date-formatted string node to a reference to the shared
+ * brand definition, in every position. Nodes are rebuilt, never mutated:
+ * the schemas here are the compiled document's own frozen subtrees.
+ * @param {any} node
+ * @param {string} name - the brand definition's name in this document
+ * @returns {any}
+ */
+function brandDates(node, name) {
+  if (Array.isArray(node)) return node.map((item) => brandDates(item, name));
+  if (node === null || typeof node !== 'object') return node;
+  /** @type {Record<string, any>} */
+  const out = {};
+  const keys = Object.keys(node);
+  for (let i = 0; i < keys.length; i++) setObjectMember(out, keys[i], brandDates(node[keys[i]], name));
+  if (!DATE_FORMATS.includes(/** @type {any} */ (out.format))) return out;
+  const { type, format: _format, ...rest } = out;
+  if (type === 'string') return { $ref: `#/$defs/${name}`, ...rest };
+  // a nullable date: the brand or null, the rest of the node kept
+  if (Array.isArray(type) && type.length === 2 && type.includes('string') && type.includes('null')) {
+    return { anyOf: [{ $ref: `#/$defs/${name}` }, { type: 'null' }], ...rest };
+  }
+  return out;
+}
+
+/** Whether a document reaches a date-formatted string anywhere. */
+function usesDates(node) {
+  if (Array.isArray(node)) return node.some(usesDates);
+  if (node === null || typeof node !== 'object') return false;
+  if (DATE_FORMATS.includes(node.format)) return true;
+  return Object.values(node).some(usesDates);
+}
+
+/**
+ * Replace the brand definition's compiled declaration — a plain
+ * `string` — with the brand intersection `string & { __jarenTag:
+ * 'date-time' }`, structurally identical to `@jarenjs/db`'s and
+ * `@jarenjs/linq`'s.
+ * @param {any} model
+ * @param {string} name
+ */
+function brandDeclaration(model, name) {
+  const declaration = model.declarations.find((/** @type {any} */ d) => d.name === name);
+  /* c8 ignore next -- the definition is added exactly when it is referenced */
+  if (declaration === undefined) return;
+  declaration.type = {
+    kind: 'intersection',
+    parts: [{ kind: 'primitive', primitive: 'string' }, {
+      kind: 'object',
+      members: [{
+        kind: 'member', name: '__jarenTag',
+        type: { kind: 'literal', value: 'date-time' }, required: true,
+        constraints: [], doc: [],
+      }],
+    }],
+  };
+  declaration.doc = ['An RFC 3339 string branded for the date operators;',
+    'structurally identical to the @jarenjs/linq and @jarenjs/db brand.'];
+}
+
 /**
  * The type model of a contract: the synthetic `$defs` root, the row per
  * operation the stylesheet renders, and the rendered declarations.
@@ -117,7 +194,20 @@ export function contractTypeModel(contract, ops, source) {
   }
   const names = Object.keys(contractDefs);
   for (let i = 0; i < names.length; i++) setObjectMember(defs, names[i], contractDefs[names[i]]);
-  const model = compileEmitModel({ $defs: defs }, { name: 'Contract', source });
+  /** @type {Record<string, any>} */
+  let root = defs;
+  /** @type {string | null} */
+  let brand = null;
+  if (usesDates(defs)) {
+    // the brand takes its own name unless the contract already spells it
+    brand = taken.has(DATE_TIME) ? unique(DATE_TIME) : DATE_TIME;
+    root = { [brand]: { type: 'string' } };
+    const branded = brandDates(defs, brand);
+    const keys = Object.keys(branded);
+    for (let i = 0; i < keys.length; i++) setObjectMember(root, keys[i], branded[keys[i]]);
+  }
+  const model = compileEmitModel({ $defs: root }, { name: 'Contract', source });
+  if (brand !== null) brandDeclaration(model, brand);
   const declarations = model.declarations.filter((d) => d.name !== model.root);
   const types = renderTypeScript({ ...model, declarations }, { banner: false });
   return { types, rows, model: { ...model, declarations } };