experimental-a2 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- 197b719: Add `idempotentId(...parts: string[])` to derive stable UUIDv8 event IDs from
+  ordered strings in server and browser code. Existing IDs and automatic ID
+  generation are unchanged.
+
 ## 0.14.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -2,4 +2,8 @@ import { a as ContractEvent, c as PresenceDefs, d as PresenceSnapshot, f as Redu
 import { i as Event } from "./store-D_yhNdPz.js";
 import { i as NonRetriableError, n as A2ErrorCode, r as A2ServerErrorCode, t as A2Error } from "./errors-DvhSXnxk.js";
 import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-CpeclqB2.js";
-export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2ServerErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, NonRetriableError, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };
+//#region src/idempotent-id.d.ts
+declare function idempotentId(...parts: string[]): Promise<string>;
+//#endregion
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2ServerErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, NonRetriableError, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract, idempotentId };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/idempotent-id.ts"],"mappings":";;;;;iBAAsB,gBAAgB,kBAAkB"}

package/dist/index.js

@@ -1,3 +1,15 @@
 import { t as contract } from "./contract-CKRg_E4q.js";
 import { n as NonRetriableError, t as A2Error } from "./errors-DCk6ch5n.js";
-export { A2Error, NonRetriableError, contract };
+//#region src/idempotent-id.ts
+async function idempotentId(...parts) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(parts)));
+	const bytes = new Uint8Array(digest).slice(0, 16);
+	bytes[6] = bytes[6] & 15 | 128;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+//#endregion
+export { A2Error, NonRetriableError, contract, idempotentId };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/idempotent-id.ts"],"sourcesContent":["export async function idempotentId(...parts: string[]): Promise<string> {\n  const digest = await crypto.subtle.digest(\n    'SHA-256',\n    new TextEncoder().encode(JSON.stringify(parts)),\n  )\n  const bytes = new Uint8Array(digest).slice(0, 16)\n  bytes[6] = (bytes[6]! & 0x0f) | 0x80\n  bytes[8] = (bytes[8]! & 0x3f) | 0x80\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`\n}\n"],"mappings":";;;AAAA,eAAsB,aAAa,GAAG,OAAkC;CACtE,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,KAAK,CAAC,CAChD;CACA,MAAM,QAAQ,IAAI,WAAW,MAAM,CAAC,CAAC,MAAM,GAAG,EAAE;CAChD,MAAM,KAAM,MAAM,KAAM,KAAQ;CAChC,MAAM,KAAM,MAAM,KAAM,KAAQ;CAChC,MAAM,MAAM,MAAM,KAAK,QAAQ,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;CAC7E,OAAO,GAAG,IAAI,MAAM,GAAG,CAAC,EAAE,GAAG,IAAI,MAAM,GAAG,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE;AAC7G"}

package/docs/reference/01-api.mdx

@@ -63,6 +63,31 @@ The shared base for A2 failures, discriminated by `code`. The session
 client exposes its `A2ClientError` subclass. See
 [Errors](/reference/errors).
 
+### `idempotentId(...parts)`
+
+`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
+from an ordered tuple of strings. It runs on the server and in the browser.
+
+```ts shared/request-id.ts
+import { idempotentId } from 'experimental-a2'
+
+export const id = await idempotentId('orders', 'shop-7', 'request-42')
+```
+
+Pass the result as an event's `id` when retries should converge on the same
+event. The same tuple produces the same ID across runtimes and A2 versions.
+String boundaries, order, and case matter; strings are not normalized.
+Empty strings and an empty tuple are valid inputs.
+
+Every argument has the same role. A prefix such as `'orders'` is a namespace
+by convention. Include enough context to distinguish operations across
+contracts and sessions, since event IDs are globally unique within a store.
+
+The helper performs no I/O. A2 preserves explicit IDs and keeps its automatic
+ID generation unchanged. Changing an existing application's ID recipe changes
+retry identity, so retries of previously committed requests need to retain
+their original IDs.
+
 ## `experimental-a2/server`
 
 ### `handler(entry)`

package/examples/playground/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.14.1",
+    "experimental-a2": "0.15.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",

package/src/idempotent-id.ts

@@ -0,0 +1,11 @@
+export async function idempotentId(...parts: string[]): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(JSON.stringify(parts)),
+  )
+  const bytes = new Uint8Array(digest).slice(0, 16)
+  bytes[6] = (bytes[6]! & 0x0f) | 0x80
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}

package/src/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { contract } from './contract.ts'
+export { idempotentId } from './idempotent-id.ts'
 export type {
   AppendInput,
   Contract,