@afora/core 0.0.8 → 0.0.9

package/dist/testing/index.js

@@ -1,12 +1,361 @@
-import"../index-qxfkyd6k.js";
 import {
+  exceptionOf2,
+  SCHEMA_VERSION_KEY2,
   RepositoryUniqueViolation2,
   RepositoryEntityNotFound2,
-  RepositoryConcurrencyConflict2,
+  RepositoryConcurrencyConflict2
+} from "../index-xegv6a1p.js";
+import {
+  repositoryOf2,
+  useCaseOf2
+} from "../index-3aae5jfq.js";
+import {
+  outputOf2,
+  applicationOf2,
   blueprintOf2,
-  entityOf2
-} from "../index-t5qwtyj5.js";
+  commandOf2,
+  entityOf2,
+  recordOf2
+} from "../index-ny3as79r.js";
+import"../index-hg1z2s2v.js";
+import"../index-y280ew0k.js";
+
+// src/testing/http-provider-contract.ts
+var Note = recordOf2(blueprintOf2((ctx) => ({ title: ctx.string, secret: ctx.password })));
+var Rejected = exceptionOf2({
+  layer: "use-case" /* UseCase */,
+  name: "ContractRejected",
+  message: "rejected"
+});
+var Echo = blueprintOf2((ctx) => ({
+  id: ctx.optional.string,
+  page: ctx.optional.integer,
+  flag: ctx.optional.boolean,
+  locale: ctx.optional.string,
+  session: ctx.optional.string,
+  title: ctx.optional.string,
+  caller: ctx.optional.string,
+  tenant: ctx.optional.string
+}));
+function operations() {
+
+  class Get extends useCaseOf2({
+    name: "ContractGet",
+    blueprint: blueprintOf2((ctx) => ({
+      id: ctx.string,
+      page: ctx.optional.integer,
+      flag: ctx.optional.boolean
+    })),
+    response: Echo,
+    route: { method: "get", path: "/items/{id}" }
+  }) {
+    async execute() {
+      return { ...this.input };
+    }
+  }
+
+  class Change extends useCaseOf2({
+    name: "ContractChange",
+    blueprint: blueprintOf2((ctx) => ({
+      id: ctx.string,
+      page: ctx.integer,
+      locale: ctx.optional.string,
+      session: ctx.optional.string,
+      title: ctx.string
+    })),
+    response: Echo,
+    context: blueprintOf2((ctx) => ({ tenant: ctx.optional.string })),
+    errors: [Rejected],
+    route: {
+      method: "put",
+      path: "/items/{id}",
+      status: 201,
+      query: ["page"],
+      headers: { locale: "accept-language" },
+      cookie: { session: "sid" }
+    }
+  }) {
+    async execute() {
+      if (this.input.title === "reject")
+        throw new Rejected({ source: "x" });
+      if (this.input.title === "crash")
+        throw new Error("internal detail");
+      return { ...this.input, tenant: this.context.tenant };
+    }
+  }
 
+  class Remove extends useCaseOf2({
+    name: "ContractRemove",
+    blueprint: blueprintOf2((ctx) => ({ id: ctx.string })),
+    response: blueprintOf2(() => ({})),
+    route: { method: "delete", path: "/items/{id}", status: 204 }
+  }) {
+    async execute() {
+      return {};
+    }
+  }
+
+  class Reveal extends useCaseOf2({
+    name: "ContractReveal",
+    blueprint: blueprintOf2(() => ({})),
+    response: blueprintOf2(() => ({ note: Note })),
+    route: { method: "get", path: "/note" }
+  }) {
+    async execute() {
+      return { note: new Note({ title: "t", secret: await hashed() }) };
+    }
+  }
+
+  class Mine extends useCaseOf2({
+    name: "ContractMine",
+    blueprint: blueprintOf2(() => ({})),
+    response: Echo,
+    context: blueprintOf2((ctx) => ({ caller: ctx.string })),
+    route: { method: "get", path: "/mine" },
+    access: { scopes: ["items:read"], context: { caller: "subject" } }
+  }) {
+    async execute() {
+      return { caller: this.context.caller };
+    }
+  }
+
+  class Enter extends useCaseOf2({
+    name: "ContractEnter",
+    blueprint: blueprintOf2((ctx) => ({ title: ctx.string })),
+    response: blueprintOf2((ctx) => ({
+      title: ctx.string,
+      token: ctx.string,
+      refreshToken: ctx.string
+    })),
+    route: {
+      method: "post",
+      path: "/enter",
+      setCookie: {
+        token: { name: "sid", secure: false },
+        refreshToken: { name: "rid", secure: false, path: "/refresh" }
+      }
+    }
+  }) {
+    async execute() {
+      return { title: this.input.title, token: "t 1", refreshToken: "" };
+    }
+  }
+  return commandOf2({
+    name: "Contract",
+    useCases: {
+      get: Get,
+      change: Change,
+      remove: Remove,
+      reveal: Reveal,
+      mine: Mine,
+      enter: Enter
+    }
+  });
+}
+async function hashed() {
+  return "$argon2id$v=19$m=65536,t=2,p=1$c29tZXNhbHRzb21lc2FsdA$4VbQ3OqJ7xk8Y0mG0iZ1c2k1m2Qe0sQeJ7xk8Y0mG0i";
+}
+var authenticator = (request) => {
+  const token = request.header("authorization");
+  if (token === "Bearer reader")
+    return { subject: "u1", scopes: ["items:read"] };
+  if (token === "Bearer other")
+    return { subject: "u2", scopes: [] };
+  return null;
+};
+function httpProviderContract(name, settings, runner) {
+  const { describe, it, expect } = runner;
+  const origin = "http://contract.test";
+  const withServer = async (options, body, hooks = { authenticator }) => {
+    const server = outputOf2({
+      name: "Contract",
+      commands: [operations()],
+      statuses: { ContractRejected: 409 },
+      pipe: [settings.sink(options, hooks)]
+    }).build();
+    try {
+      await body(async (method, path, init = {}) => {
+        const hasBody = init.body !== undefined;
+        const response = await settings.fetch(server, new Request(`${origin}${path}`, {
+          method,
+          headers: {
+            ...hasBody ? { "content-type": "application/json" } : {},
+            ...init.headers
+          },
+          ...hasBody ? {
+            body: typeof init.body === "string" ? init.body : JSON.stringify(init.body)
+          } : {}
+        }));
+        const text = await response.text();
+        let json;
+        try {
+          json = text === "" ? undefined : JSON.parse(text);
+        } catch {
+          json = undefined;
+        }
+        return {
+          status: response.status,
+          type: (response.headers.get("content-type") ?? "").split(";")[0],
+          headers: response.headers,
+          text,
+          json
+        };
+      });
+    } finally {
+      await settings.close?.(server);
+    }
+  };
+  describe(`${name}: HTTP provider contract`, () => {
+    it("serves the route a use case declares, path and query coerced", async () => {
+      await withServer({ basePath: "/api" }, async (send) => {
+        const found = await send("GET", "/api/items/a%20b?page=2&flag=true");
+        expect(found.status).toBe(200);
+        expect(found.type).toBe("application/json");
+        expect(found.json).toEqual({ id: "a b", page: 2, flag: true });
+      });
+    });
+    it("reads each key where the route places it, over the body", async () => {
+      await withServer({}, async (send) => {
+        const changed = await send("PUT", "/items/p?page=3", {
+          headers: { "accept-language": "pt-BR", cookie: "x=1; sid=s%201" },
+          body: { id: "from-body", page: 9, title: "T" }
+        });
+        expect(changed.status).toBe(201);
+        expect(changed.json).toEqual({
+          id: "p",
+          page: 3,
+          locale: "pt-BR",
+          session: "s 1",
+          title: "T"
+        });
+      });
+    });
+    it("fills the context from headers", async () => {
+      await withServer({ context: { headers: { tenant: "x-tenant" } } }, async (send) => {
+        const changed = await send("PUT", "/items/p?page=1", {
+          headers: { "x-tenant": "acme" },
+          body: { title: "T" }
+        });
+        expect(changed.json.tenant).toBe("acme");
+      });
+    });
+    it("answers invalid input and invalid JSON with a 400 problem", async () => {
+      await withServer({}, async (send) => {
+        const invalid = await send("PUT", "/items/p?page=1", {
+          body: { title: 1 }
+        });
+        expect(invalid.status).toBe(400);
+        expect(invalid.type).toBe("application/problem+json");
+        const problem = invalid.json;
+        expect(problem.title).toBe("InvalidUseCaseInput");
+        expect(problem.issues.map((issue) => issue.path)).toEqual([["title"]]);
+        const notJson = await send("PUT", "/items/p?page=1", {
+          body: "{nope"
+        });
+        expect(notJson.status).toBe(400);
+        expect(notJson.json.title).toBe("InvalidRequestBody");
+      });
+    });
+    it("gives errors the status of the output, and hides internal ones", async () => {
+      await withServer({}, async (send) => {
+        const rejected = await send("PUT", "/items/p?page=1", {
+          body: { title: "reject" }
+        });
+        expect(rejected.status).toBe(409);
+        expect(rejected.type).toBe("application/problem+json");
+        const crashed = await send("PUT", "/items/p?page=1", {
+          body: { title: "crash" }
+        });
+        expect(crashed.status).toBe(500);
+        expect(crashed.text.includes("internal detail")).toBe(false);
+      });
+      await withServer({ debug: true }, async (send) => {
+        const crashed = await send("PUT", "/items/p?page=1", {
+          body: { title: "crash" }
+        });
+        expect(crashed.text.includes("internal detail")).toBe(true);
+      });
+    });
+    it("answers a 204 without a body, and an unknown route with a 404 problem", async () => {
+      await withServer({}, async (send) => {
+        const removed = await send("DELETE", "/items/p");
+        expect(removed.status).toBe(204);
+        expect(removed.text).toBe("");
+        const unknown = await send("GET", "/nowhere");
+        expect(unknown.status).toBe(404);
+        expect(unknown.type).toBe("application/problem+json");
+        expect(unknown.json.title).toBe("NotFound");
+      });
+    });
+    it("masks sensitive values", async () => {
+      await withServer({}, async (send) => {
+        const revealed = await send("GET", "/note");
+        expect(revealed.json).toEqual({
+          note: { title: "t", secret: "********" }
+        });
+      });
+    });
+    it("enforces the access of a use case", async () => {
+      await withServer({}, async (send) => {
+        const anonymous = await send("GET", "/mine");
+        expect(anonymous.status).toBe(401);
+        expect(anonymous.json.title).toBe("Unauthenticated");
+        const other = await send("GET", "/mine", {
+          headers: { authorization: "Bearer other" }
+        });
+        expect(other.status).toBe(403);
+        const reader = await send("GET", "/mine", {
+          headers: { authorization: "Bearer reader" }
+        });
+        expect(reader.status).toBe(200);
+        expect(reader.json).toEqual({ caller: "u1" });
+      });
+      await withServer({}, async (send) => {
+        const closed = await send("GET", "/mine", {
+          headers: { authorization: "Bearer reader" }
+        });
+        expect(closed.status).toBe(401);
+      }, {});
+    });
+    it("sends the cookies of a route, out of the body", async () => {
+      await withServer({}, async (send) => {
+        const entered = await send("POST", "/enter", { body: { title: "T" } });
+        expect(entered.status).toBe(200);
+        expect(entered.json).toEqual({ title: "T" });
+        expect(entered.headers.getSetCookie()).toEqual([
+          "sid=t%201; Path=/; HttpOnly; SameSite=Lax",
+          "rid=; Path=/refresh; HttpOnly; SameSite=Lax; Max-Age=0"
+        ]);
+      });
+    });
+    it("puts the request id on successes and problems", async () => {
+      await withServer({ requestId: true }, async (send) => {
+        const sent = await send("GET", "/items/a", {
+          headers: { "x-request-id": "abc-1" }
+        });
+        expect(sent.headers.get("x-request-id")).toBe("abc-1");
+        const problem = await send("GET", "/mine");
+        expect((problem.headers.get("x-request-id") ?? "").length).toBe(36);
+      });
+    });
+    it("serves the document of the same routes", async () => {
+      await withServer({
+        basePath: "/api",
+        docs: { path: "/openapi.json", info: { title: "C", version: "1" } }
+      }, async (send) => {
+        const docs = await send("GET", "/openapi.json");
+        expect(docs.status).toBe(200);
+        expect(docs.type).toBe("application/json");
+        expect(Object.keys(docs.json.paths).sort()).toEqual([
+          "/api/enter",
+          "/api/items/{id}",
+          "/api/mine",
+          "/api/note"
+        ]);
+      });
+    });
+  });
+}
 // src/testing/memory-publisher.ts
 function memoryPublisher() {
   const published = [];
@@ -37,6 +386,11 @@ function row(overrides = {}) {
   const id = `id-${String(sequence).padStart(4, "0")}`;
   return { id, email: `${id}@example.com`, name: id, ...overrides };
 }
+function evolvedRow(overrides = {}) {
+  sequence += 1;
+  const id = `0190a1b2-c3d4-7e5f-8a9b-${String(sequence).padStart(12, "0")}`;
+  return { ...row(), id, email: `${sequence}@example.com`, ...overrides };
+}
 async function failure(promise) {
   try {
     await promise;
@@ -936,9 +1290,146 @@ function providerContract(runner, makeProvider, options = {}) {
         expect(await provider.count(context, { now: NOW })).toBe(1);
       });
     });
+    describe("schema evolution", () => {
+      const evolving = (key) => (name, body) => it(name, async () => {
+        if (options.schemaEvolution === false)
+          return;
+        if (key && options.schemaVersionKey === false)
+          return;
+        await body();
+      });
+      const always = evolving(false);
+      const keyed = evolving(true);
+      const contextFor = (entity, name) => ({
+        entity,
+        name: `${name}Repository`,
+        unique: ["id", "email"],
+        indexes: {},
+        env: {}
+      });
+      const accountsOf = (options = {}) => class Accounts extends entityOf2(blueprintOf2((ctx) => ({
+        email: ctx.string,
+        name: ctx.string,
+        age: ctx.integer.with({ fill: 18 }),
+        visits: ctx.integer.with({ renamedFrom: "n" }),
+        active: ctx.optionalOf(ctx.boolean)
+      })), {
+        name: "Accounts",
+        unique: ["email"],
+        ...options.schemaVersion === undefined ? {} : {
+          schemaVersion: options.schemaVersion,
+          upgrade: {
+            2: (data) => ({ ...data, active: true })
+          }
+        },
+        ...options.previousNames === undefined ? {} : { previousNames: options.previousNames }
+      }) {
+      };
+      async function setup(entity) {
+        const provider = await makeProvider();
+        const Accounts = repositoryOf2({
+          entity,
+          actions: ["findMany"],
+          provider
+        });
+        const app = applicationOf2({
+          name: "contract",
+          entities: { Accounts: entity },
+          repositories: { Accounts }
+        });
+        const context = contextFor(entity, "Accounts");
+        const old = [evolvedRow({ n: 3 }), evolvedRow({ n: 5 })];
+        for (const data of old)
+          await provider.insert(context, data);
+        const read = async () => (await Accounts.findMany()).map((account) => account.toJSON());
+        return { provider, app, context, old, read };
+      }
+      always("reads a row of an older shape back in the current one", async () => {
+        const { old, read } = await setup(accountsOf());
+        const [first] = await read();
+        expect(first?.id).toBe(old[0]?.id);
+        expect([first?.age, first?.visits]).toEqual([18, 3]);
+        expect(Object.hasOwn(first ?? {}, "n")).toBe(false);
+      });
+      keyed("reads a row of an older version through upgrade", async () => {
+        const { read } = await setup(accountsOf({ schemaVersion: 2 }));
+        const [first] = await read();
+        expect([first?.age, first?.visits, first?.active]).toEqual([
+          18,
+          3,
+          true
+        ]);
+      });
+      always("the backfill reports in check and rewrites in apply", async () => {
+        const { provider, app, context, old } = await setup(accountsOf());
+        const check = await app.migrate({ mode: "check", pageSize: 1 });
+        expect([
+          check.entities.Accounts?.scanned,
+          check.entities.Accounts?.upgraded
+        ]).toEqual([2, 2]);
+        const untouched = await provider.findOne(context, {
+          where: { id: old[0]?.id }
+        });
+        expect(untouched?.n).toBe(3);
+        await app.migrate({ mode: "apply", pageSize: 1 });
+        const stored = await provider.findOne(context, {
+          where: { id: old[0]?.id }
+        });
+        expect([stored?.age, stored?.visits]).toEqual([18, 3]);
+        expect(stored?.n ?? undefined).toBe(undefined);
+        const again = await app.migrate({ mode: "check" });
+        expect(again.entities.Accounts?.upToDate).toBe(2);
+      });
+      keyed("the backfill stores the schema version", async () => {
+        const { provider, app, context, old } = await setup(accountsOf({ schemaVersion: 2 }));
+        await app.migrate({ mode: "apply" });
+        const stored = await provider.findOne(context, {
+          where: { id: old[1]?.id }
+        });
+        expect([stored?.[SCHEMA_VERSION_KEY2], stored?.active]).toEqual([
+          2,
+          true
+        ]);
+        const again = await app.migrate({ mode: "check" });
+        expect(again.entities.Accounts?.upToDate).toBe(2);
+      });
+      always("the backfill moves the rows of a previous name", async () => {
+        const entity = accountsOf({ previousNames: ["One"] });
+        const provider = await makeProvider();
+        const Accounts = repositoryOf2({
+          entity,
+          actions: ["findMany"],
+          provider
+        });
+        const app = applicationOf2({
+          name: "contract",
+          entities: { Accounts: entity },
+          repositories: { Accounts }
+        });
+
+        class One extends entityOf2(blueprintOf2((ctx) => ({ email: ctx.string, name: ctx.string })), { name: "One" }) {
+        }
+        const previous = contextFor(One, "One");
+        const current = contextFor(entity, "Accounts");
+        const old = [evolvedRow({ n: 1 }), evolvedRow({ n: 2 })];
+        for (const data of old)
+          await provider.insert(previous, data);
+        const check = await app.migrate({ mode: "check" });
+        expect(check.entities.Accounts?.movedFromPreviousNames).toBe(2);
+        expect(await provider.count(current)).toBe(0);
+        await app.migrate({ mode: "apply", pageSize: 1 });
+        expect(await provider.count(current)).toBe(2);
+        expect(await provider.count(previous)).toBe(2);
+        expect((await Accounts.findMany()).map((account) => account.visits)).toEqual([1, 2]);
+        await app.migrate({ mode: "apply", destructive: true, pageSize: 1 });
+        expect(await provider.count(previous)).toBe(0);
+        expect(await provider.count(current)).toBe(2);
+      });
+    });
   });
 }
 export {
+  httpProviderContract,
   memoryPublisher,
   providerContract
 };

package/dist/testing/provider-contract.d.ts

@@ -1,4 +1,4 @@
-import { type IRepositoryProvider } from "../index.js";
+import { type IRepositoryProvider } from "../adapters.js";
 /** The parts of a test runner the kit uses; `bun:test`, vitest and jest fit. */
 export interface ContractRunner {
     describe(name: string, body: () => void): void;
@@ -32,6 +32,22 @@ export interface ProviderContractOptions {
     readonly atomic?: boolean;
     /** Run the cases of expired records. Defaults to `provider.capabilities?.expiry`. */
     readonly expiry?: boolean;
+    /**
+     * Run the cases of schema evolution, through repositories and
+     * `app.migrate` over the basic methods: an old row read back upgraded,
+     * the backfill in check and apply, rows moved from a previous name.
+     * Default `true`. Their entities are named `Accounts` (and `One`, the
+     * previous name), with the keys of the other cases; `createdAt` and
+     * `updatedAt` are never written.
+     */
+    readonly schemaEvolution?: boolean;
+    /**
+     * Run the schema evolution cases that store the version key
+     * (`SCHEMA_VERSION_KEY`, `"$v"`) in rows, for an entity declared with
+     * `schemaVersion`. Default `true`; a provider with a fixed set of
+     * columns needs one for it (or maps `context.schema.key` to its own).
+     */
+    readonly schemaVersionKey?: boolean;
 }
 /**
  * Registers the behavior every `IRepositoryProvider` v2 must have. Pass the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@afora/core",
-	"version": "0.0.8",
+	"version": "0.0.9",
 	"description": "Domain modeling on TypeBox: entities with invariants, repositories, use cases, sensitive data masking and layered exceptions, usable by any Standard Schema consumer.",
 	"keywords": [
 		"domain-driven-design",
@@ -40,6 +40,11 @@
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
 		},
+		"./adapters": {
+			"types": "./dist/adapters.d.ts",
+			"import": "./dist/adapters.js",
+			"default": "./dist/adapters.js"
+		},
 		"./experimental": {
 			"types": "./dist/experimental.d.ts",
 			"import": "./dist/experimental.js",
@@ -68,9 +73,11 @@
 		"lint": "biome lint .",
 		"fmt": "biome check --write .",
 		"knip": "knip",
-		"build": "rm -rf dist && bun build ./src/index.ts ./src/experimental.ts ./src/testing/index.ts --outdir ./dist --target node --format esm --splitting --packages external && tsc -p tsconfig.build.json",
+		"build": "rm -rf dist && bun build ./src/index.ts ./src/adapters.ts ./src/experimental.ts ./src/testing/index.ts --outdir ./dist --target node --format esm --splitting --packages external && tsc -p tsconfig.build.json",
 		"postbuild": "bun scripts/add-dts-extensions.ts",
 		"bench": "cd bench && bun install && bun run.ts",
+		"bench:guard": "cd bench && bun install && bun run.ts --guard",
+		"bench:check": "cd bench && bun install && bun run.ts --check",
 		"smoke": "bun run build && node scripts/smoke.mjs",
 		"test:types": "bun run build && bun tests/types-compat/run.ts",
 		"test:type-perf": "bun run build && bun test ./tests/type-perf",
@@ -78,15 +85,21 @@
 		"docs:links": "bun scripts/check-doc-links.ts",
 		"test:interop": "cd examples/interop && bun install && bun test",
 		"test:blog": "cd examples/blog && bun install && bun test",
+		"test:agent-built": "cd examples/agent-built && bun install && bun check && bun test",
+		"eval:agent-built": "cd examples/agent-built && bun install && bun run eval:all",
 		"prepare": "husky",
 		"prepublishOnly": "bun run typecheck && bun test && bun run smoke",
 		"test:codegen": "bun run --cwd packages/codegen test",
 		"test:roundtrip": "bun run --cwd packages/codegen test:roundtrip",
 		"test:mcp": "bun test --cwd packages/mcp",
 		"test:hono": "bun test --cwd packages/hono",
+		"test:fastify": "bun test --cwd packages/fastify",
+		"test:express": "bun test --cwd packages/express",
+		"test:elysia": "bun test --cwd packages/elysia",
 		"test:ws": "bun test --cwd packages/ws",
 		"test:drizzle": "bun test --cwd packages/drizzle",
-		"build:packages": "bun run build && bun run --cwd packages/codegen build && bun run --cwd packages/mcp build && bun run --cwd packages/hono build && bun run --cwd packages/ws build && bun run --cwd packages/drizzle build"
+		"test:dynamodb": "bun test --cwd packages/dynamodb",
+		"build:packages": "bun run build && bun run --cwd packages/codegen build && bun run --cwd packages/mcp build && bun run --cwd packages/hono build && bun run --cwd packages/fastify build && bun run --cwd packages/express build && bun run --cwd packages/elysia build && bun run --cwd packages/ws build && bun run --cwd packages/drizzle build && bun run --cwd packages/dynamodb build"
 	},
 	"dependencies": {
 		"slugify": "^1.6.9"