experimental-a2 0.0.0

package/docs/reference/02-errors.mdx

@@ -0,0 +1,77 @@
+---
+title: Errors
+description: One error class, five codes, and clear rules about what append will never throw for.
+---
+
+## `A2Error`
+
+Everything A2 throws is an `A2Error`, a single class discriminated by
+`code`, not a subclass hierarchy. One class serializes cleanly across the
+push-route boundary and keeps `instanceof` working after bundling.
+
+```ts
+// e.g. in a route handler:
+import { A2Error } from 'experimental-a2'
+
+export async function POST(req: Request) {
+  const { orderId, payload } = await req.json()
+  try {
+    const events = await ordersServer
+      .session(orderId)
+      .append({ type: 'created', payload })
+    return Response.json(events)
+  } catch (err) {
+    if (err instanceof A2Error && err.code === 'INVALID_PAYLOAD') {
+      // err.details carries the schema issues, in Standard Schema format
+      return Response.json({ issues: err.details }, { status: 400 })
+    }
+    throw err
+  }
+}
+```
+
+## The codes
+
+| Code                      | Thrown when                                                        | Retryable |
+| ------------------------- | ------------------------------------------------------------------ | --------- |
+| `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
+| `UNKNOWN_EVENT_TYPE`      | an event type isn't in the contract's `events` map                  | no        |
+| `PARTIAL_DUPLICATE_BATCH` | a batch mixed already-appended and fresh events                     | no        |
+| `LOG_UNAVAILABLE`         | the log backend failed; nothing was written, original error as `cause` | **yes**   |
+| `LOG_NOT_CONFIGURED`      | production boot with no `log` configured (during `next build` page collection, deferred to first use) | no |
+
+Retryability is derivable from the code. `LOG_UNAVAILABLE` is the only one
+worth retrying; the rest are deterministic caller bugs, and retrying them
+is wasted work.
+
+On `PARTIAL_DUPLICATE_BATCH`: retrying an *identical* batch is not an
+error. It's an idempotent success, and you get the previously appended
+events back. Mixing already-sent events with fresh ones in a single batch
+is always a caller bug, so A2 refuses it rather than quietly reinterpret
+what "atomic" meant. The same code covers two adjacent bugs: a batch that
+contains the same id twice, and an id that was already used in a
+*different* session (event ids are globally unique). In every case,
+nothing is written.
+
+## What append never throws for
+
+- **A failing handler.** Appends always land; handler failures are retried
+  and, if persistent, [dead-letter the event](/concepts/durability#when-a-handler-keeps-failing).
+  `append` never fails because a downstream handler is failing.
+- **A duplicate of an identical batch.** That's a lost ack, not a bug.
+
+## Over the wire
+
+The push route serializes an `A2Error` as:
+
+```json
+{ "error": { "code": "INVALID_PAYLOAD", "message": "...", "details": [] } }
+```
+
+with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
+`PARTIAL_DUPLICATE_BATCH` are 400; `LOG_UNAVAILABLE` is 503.
+
+The client's `push` deserializes the body back into an `A2Error`, so client
+and server code branch on identical codes. `push` auto-retries only
+`LOG_UNAVAILABLE`. The serializer pair ships in `experimental-a2/http`, alongside
+`parsePushBody` and `sseResponse`.

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "experimental-a2",
+  "version": "0.0.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",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/a2.git",
+    "directory": "packages/a2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": {
+      "browser": "./dist/server.browser.js",
+      "default": "./dist/server.js"
+    },
+    "./client": "./dist/client.js",
+    "./react": "./dist/react.js",
+    "./ai": "./dist/ai.js",
+    "./ai/server": {
+      "browser": "./dist/ai-server.browser.js",
+      "default": "./dist/ai-server.js"
+    },
+    "./http": "./dist/http.js",
+    "./log-memory": "./dist/log-memory.js",
+    "./log-sqlite": "./dist/log-sqlite.js",
+    "./log-postgres": "./dist/log-postgres.js",
+    "./log-redis": "./dist/log-redis.js",
+    "./recovery-vercel": "./dist/recovery-vercel.js",
+    "./cache-indexeddb": "./dist/cache-indexeddb.js",
+    "./otel": "./dist/otel.js",
+    "./devtools/server": {
+      "browser": "./dist/devtools-server.browser.js",
+      "default": "./dist/devtools-server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@vercel/queue": "*",
+    "ai": "^7.0.0",
+    "ioredis": "^5.4.0",
+    "pg": "^8.11.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@vercel/queue": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "catalog:",
+    "ai": "catalog:",
+    "ioredis": "catalog:",
+    "@opentelemetry/api": "catalog:",
+    "@types/pg": "catalog:",
+    "@vercel/queue": "catalog:",
+    "pg": "catalog:",
+    "@testing-library/react": "catalog:",
+    "@types/react": "catalog:",
+    "esbuild": "catalog:",
+    "@types/react-dom": "catalog:",
+    "jsdom": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "@opentelemetry/context-async-hooks": "catalog:",
+    "@opentelemetry/sdk-trace-base": "catalog:",
+    "@types/node": "catalog:",
+    "publint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zod": "catalog:"
+  }
+}