@emeryld/rrroutes-contract 2.1.6 → 2.1.7

package/README.md

@@ -1,6 +1,13 @@
+<!--
+Summary:
+- Added end-to-end examples: quick start registry build/consume, cache keys, path interpolation, CRUD toggles/extras, and socket event validation.
+- Removed references to deprecated auth flags/legacy CLI notes; focused on current exports only.
+- Missing (future): planned socket middleware/onReceive helpers from the TODO block once implemented.
+-->
+
 # @emeryld/rrroutes-contract
 
-Core builder + registry utilities for RRRoutes. The contract package exposes the fluent DSL (`resource`, `withCrud`), the `finalize` helper, cache-key utilities, and all TypeScript inference helpers used by both the client and server packages.
+Type-safe contract toolkit for RRRoutes. Ship the HTTP route DSL (`resource` + `withCrud`), registry/finalization helpers, cache-key builder used by the client package, and shared socket event contracts.
 
 ## Installation
 
@@ -10,52 +17,239 @@ pnpm add @emeryld/rrroutes-contract
 npm install @emeryld/rrroutes-contract
 ```
 
-`zod` ships as a dependency so you do not need to install it separately.
+`zod` ships as a dependency—nothing extra to install.
 
-## Quick start
+## Quick start (build + consume a registry)
 
 ```ts
-import { resource, finalize } from '@emeryld/rrroutes-contract';
+import {
+  buildCacheKey,
+  compilePath,
+  finalize,
+  InferOutput,
+  InferParams,
+  InferQuery,
+  resource,
+} from '@emeryld/rrroutes-contract';
 import { z } from 'zod';
 
-const users = resource('/v1')
+// 1) Describe your API
+const leaves = resource('/v1')
   .sub('users', (users) =>
     users
       .get({
-        querySchema: z.object({ search: z.string().optional() }),
+        querySchema: z.object({
+          search: z.string().optional(),
+          limit: z.coerce.number().min(1).max(50).default(20),
+        }),
         outputSchema: z.array(z.object({ id: z.string().uuid(), email: z.string().email() })),
+        description: 'Find users',
       })
       .routeParameter('userId', z.string().uuid(), (user) =>
-        user.get({
-          outputSchema: z.object({ id: z.string().uuid(), email: z.string().email() }),
+        user.patch({
+          bodySchema: z.object({ name: z.string().min(1) }),
+          outputSchema: z.object({ ok: z.literal(true) }),
         }),
       )
       .done(),
   )
   .done();
 
-export const registry = finalize([...users]);
+// 2) Freeze it into a registry for typed lookups
+export const registry = finalize(leaves);
+
+// 3) Consume a leaf with full types
+const leaf = registry.byKey['PATCH /v1/users/:userId'];
+type Params = InferParams<typeof leaf>; // { userId: string }
+type Query = InferQuery<typeof leaf>;   // never (no query)
+type Output = InferOutput<typeof leaf>; // { ok: true }
+
+// 4) Build URLs + cache keys (React Query friendly)
+const url = compilePath(leaf.path, { userId: 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2' });
+const key = buildCacheKey({ leaf, params: { userId: 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2' } });
+// key => ['patch', 'v1', 'users', 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2', { userId: 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2' }]
 ```
 
-`registry.all` retains the readonly tuple of leaves, while `registry.byKey['GET /v1/users']` gives you autocomplete-safe access to a single endpoint.
+## Detailed usage
 
-## Scripts
+### Fluent route builder
 
-Run everything from the repo root using pnpm:
+```ts
+import { resource } from '@emeryld/rrroutes-contract';
+import { z } from 'zod';
 
-```sh
-pnpm install
-pnpm --filter @emeryld/rrroutes-contract build    # tsup + d.ts
-pnpm --filter @emeryld/rrroutes-contract test     # optional, via Jest
+const leaves = resource('/api') // base path, optional inherited cfg
+  .with({ feed: false }) // merges flags into descendants (extend NodeCfg via declaration merging if you add your own)
+  .sub('projects', (projects) =>
+    projects
+      .get({
+        feed: true, // infinite/feed for clients
+        querySchema: z.object({ cursor: z.string().optional(), limit: z.coerce.number().default(25) }),
+        outputSchema: z.object({
+          items: z.array(z.object({ id: z.string(), name: z.string() })),
+          nextCursor: z.string().optional(),
+        }),
+      })
+      .post({
+        bodySchema: z.object({ name: z.string().min(1) }),
+        outputSchema: z.object({ id: z.string(), name: z.string() }),
+        description: 'Create a project',
+      })
+      .routeParameter('projectId', z.string().uuid(), (project) =>
+        project
+          .get({ outputSchema: z.object({ id: z.string(), name: z.string() }) })
+          .patch({
+            bodySchema: z.object({ name: z.string().min(1) }),
+            outputSchema: z.object({ id: z.string(), name: z.string() }),
+          })
+          .sub('avatar', (avatar) =>
+            avatar
+              .put({
+                bodyFiles: [{ name: 'avatar', maxCount: 1 }], // signals multipart upload
+                bodySchema: z.object({ avatar: z.instanceof(Blob) }),
+                outputSchema: z.object({ ok: z.literal(true) }),
+              })
+              .done(),
+          )
+          .done(),
+      )
+      .done(),
+  )
+  .done();
 ```
 
-## Publishing
+- `sub(name, [cfg], builder?)` nests paths (`/api/projects`).
+- `routeParameter(name, schema, builder)` creates `/:name` segments and merges param schemas downward.
+- Methods (`get/post/put/patch/delete`) merge the active param schema unless you override via `paramsSchema`.
+- `done()` closes a branch and returns the collected readonly tuple of leaves.
 
-Once the workspace is built, publish just this package from its folder:
+### Registry helpers, URL building, and typing
 
-```sh
-cd packages/contract
-npm publish --access public
+```ts
+import {
+  buildCacheKey,
+  compilePath,
+  finalize,
+  InferBody,
+  InferOutput,
+  SubsetRoutes,
+} from '@emeryld/rrroutes-contract';
+
+const registry = finalize(leaves);
+const leaf = registry.byKey['PATCH /api/projects/:projectId'];
+
+// TypeScript helpers
+type Body = InferBody<typeof leaf>;     // { name: string }
+type Output = InferOutput<typeof leaf>; // { id: string; name: string }
+
+// Runtime helpers
+const url = compilePath(leaf.path, { projectId: '123' }); // "/api/projects/123"
+const cacheKey = buildCacheKey({ leaf, params: { projectId: '123' } });
+
+// Typed subsets for routers/microfrontends
+type ProjectRoutes = SubsetRoutes<typeof registry.all, '/api/projects'>;
+```
+
+- `finalize(leaves)` freezes the tuple and provides `byKey['METHOD /path']`, `all`, and `log(logger)`.
+- `compilePath` throws if required params are missing; wrap user-provided values in try/catch.
+- `buildCacheKey` produces the deterministic tuple the client package uses for React Query; reuse it for manual invalidation.
+
+### CRUD helper (`withCrud` / `resourceWithCrud`)
+
+```ts
+import { CrudDefaultPagination, finalize, resource, withCrud } from '@emeryld/rrroutes-contract';
+import { z } from 'zod';
+
+const r = withCrud(resource('/v1'));
+
+const leaves = r
+  .crud(
+    'articles',
+    {
+      paramSchema: z.string().uuid(), // value schema; becomes :articlesId
+      itemOutputSchema: z.object({ id: z.string().uuid(), title: z.string(), body: z.string() }),
+      list: { querySchema: CrudDefaultPagination },
+      create: { bodySchema: z.object({ title: z.string(), body: z.string() }) },
+      update: { bodySchema: z.object({ title: z.string().optional(), body: z.string().optional() }) },
+      enable: { remove: false }, // opt out of DELETE
+    },
+    ({ collection }) =>
+      collection
+        .sub('stats', (stats) =>
+          stats
+            .get({
+              outputSchema: z.object({ total: z.number() }),
+              description: 'Extra endpoint alongside CRUD',
+            })
+            .done(),
+        )
+        .done(),
+  )
+  .done();
+
+const registry = finalize(leaves);
+// registry.byKey now includes the CRUD + extras routes with full types
 ```
 
-Make sure the version in `packages/contract/package.json` matches what you intend to release.
+- Generated routes (unless disabled): GET feed list, POST create (requires `create.bodySchema`), GET item, PATCH update (requires `update.bodySchema`), DELETE remove.
+- Defaults: list output `{ items: Item[], nextCursor?: string }`, remove output `{ ok: true }`.
+- Pass `paramSchema` as a value schema; a compatible `z.object({ <name>Id: schema })` also works at runtime.
+- `resourceWithCrud('/v1', {})` is a convenience wrapper if you want the `.crud` method available immediately.
+
+### Socket event contracts
+
+Share a typed event map between client and server.
+
+```ts
+import { defineSocketEvents, Payload } from '@emeryld/rrroutes-contract';
+import { z } from 'zod';
+
+const { config, events } = defineSocketEvents(
+  {
+    joinMetaMessage: z.object({ room: z.string() }),
+    leaveMetaMessage: z.object({ room: z.string() }),
+    pingPayload: z.object({ clientEcho: z.object({ sentAt: z.string() }) }),
+    pongPayload: z.object({ clientEcho: z.object({ sentAt: z.string() }).optional(), sinceMs: z.number().optional() }),
+  },
+  {
+    'chat:message': { message: z.object({ roomId: z.string(), text: z.string(), userId: z.string() }) },
+    'typing:update': { message: z.object({ roomId: z.string(), userId: z.string(), typing: z.boolean() }) },
+  },
+);
+
+// Typed payload extraction
+type ChatPayload = Payload<typeof events, 'chat:message'>;
+// ChatPayload -> { roomId: string; text: string; userId: string }
+
+// Server-side guard example
+function onChatMessage(raw: unknown) {
+  const parsed = events['chat:message'].message.parse(raw);
+  // parsed is strongly typed; safe to broadcast
+}
+```
+
+`config` mirrors the system events used by the socket client/server packages; `events` holds your app-specific payload schemas.
+
+### Common patterns/recipes
+
+- **Module-per-area:** export leaf tuples per domain (`usersLeaves`, `projectsLeaves`), then spread before `finalize([...usersLeaves, ...projectsLeaves])`.
+- **Shared defaults:** wrap `resource('/api')` in your own helper that immediately calls `.with(...)` for cross-cutting flags you add via declaration merging (e.g., auth tags, tracing hints).
+- **React Query integration:** use `buildCacheKey` + `queryClient.invalidateQueries({ queryKey })` to keep caches in sync, or rely on the client package’s helpers which wrap the same logic.
+- **Error handling at boundaries:** catch `compilePath` errors when interpolating user-provided params; surface a 400 instead of crashing your handler.
+
+### Edge cases and notes
+
+- `paramsSchema` on a method overrides the merged schema from `routeParameter`—useful when you need stricter validation per verb.
+- `bodyFiles` marks a route as multipart; servers can attach upload middleware, and clients should send `FormData`.
+- CRUD helper only emits create/update routes when the matching `bodySchema` is provided; delete can be disabled via `enable.remove: false`.
+- Feed-only behavior (`feed: true`) is intended for GET endpoints; clients treat them as infinite queries.
+
+## Scripts (monorepo)
+
+Run from the repo root:
+
+```sh
+pnpm --filter @emeryld/rrroutes-contract build    # tsup + d.ts
+pnpm --filter @emeryld/rrroutes-contract typecheck
+pnpm --filter @emeryld/rrroutes-contract test     # optional Jest suite
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emeryld/rrroutes-contract",
   "description": "TypeScript contract definitions for RRRoutes",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",