@effect-app/infra 4.0.0-beta.327 → 4.0.0-beta.329

package/src/Store/jsonDocument.ts

@@ -1,6 +1,8 @@
 import type { FieldValues } from "effect-app/Model/filter/types"
+import * as Option from "effect-app/Option"
 import * as S from "effect-app/Schema"
 import type { PersistenceModelType, StoreConfig } from "effect-app/Store"
+import * as Result from "effect/Result"
 import { toJsonQueryValue } from "./utils.ts"
 
 export interface JsonDocumentCodec<E extends FieldValues> {
@@ -8,6 +10,18 @@ export interface JsonDocumentCodec<E extends FieldValues> {
   readonly decode: (doc: PersistenceModelType<E>) => PersistenceModelType<E>
 }
 
+/**
+ * The store *read* boundary decode: a stored JSON document in, either the
+ * Encoded document or the `S.SchemaError` saying why it is not one.
+ *
+ * Synchronous on purpose: it runs once per document over whole result sets, so
+ * it must not allocate an Effect per row. Adapters lift the `Result` into their
+ * Effect channel once per operation (see {@link decodeStoredMany}).
+ */
+export type StoredDecode<E extends FieldValues> = (
+  doc: PersistenceModelType<E>
+) => Result.Result<PersistenceModelType<E>, S.SchemaError>
+
 const splitEtag = <E extends FieldValues>(doc: PersistenceModelType<E>) => {
   const { _etag, ...rest } = doc
   return { rest: rest as E, _etag }
@@ -18,6 +32,9 @@ const joinEtag = <E extends FieldValues>(
   _etag: string | undefined
 ): PersistenceModelType<E> => (_etag === undefined ? rest : { ...rest, _etag })
 
+/** JSON document ↔ Encoded document codec for a store's domain schema. */
+const jsonCodec = <E extends FieldValues>(schema: S.Top) => S.toCodecJson(S.toEncoded(schema)) as S.Codec<E, S.Json>
+
 /**
  * Encoded document ↔ JSON document. Prefer `Schema.toCodecJson(toEncoded(schema))`
  * when the store has a schema; otherwise lower Date/Map/Set structurally.
@@ -26,18 +43,17 @@ const joinEtag = <E extends FieldValues>(
  * document that does not match the Encoded shape fails loudly rather than being
  * read back half-decoded.
  *
- * Migrating a legacy-shaped document is therefore not this codec's job: the
- * store applies `StoreConfig.jitM` to the raw JSON document *before* calling
- * `decode` (see {@link makeStoredDecode}), which is the only place where a
- * document can be repaired. A document `jitM` does not repair is a genuine
- * failure and throws here.
+ * This is the **write** path codec: `encode` on the way to the database, and
+ * `decode` to hand the just-written document back. The read path uses
+ * {@link makeStoredDecode}, which applies `jitM` first and reports a document it
+ * does not repair as a typed `S.SchemaError` instead of throwing.
  *
  * `_etag` is infrastructure metadata rather than part of the domain document,
  * so it is split off before the codec runs and re-attached afterwards.
  */
 export const makeJsonDocumentCodec = <E extends FieldValues>(schema?: S.Top): JsonDocumentCodec<E> => {
   if (schema) {
-    const codec = S.toCodecJson(S.toEncoded(schema)) as S.Codec<E, S.Json>
+    const codec = jsonCodec<E>(schema)
     return {
       encode: (doc) => {
         const { rest, _etag } = splitEtag(doc)
@@ -58,31 +74,70 @@ export const makeJsonDocumentCodec = <E extends FieldValues>(schema?: S.Top): Js
 /**
  * The store *read* boundary: apply `jitM` to the raw JSON document - after the
  * adapter merged `defaultValues` into it - and only then decode JSON→Encoded
- * with the strict {@link makeJsonDocumentCodec} codec.
+ * with the strict `Schema.toCodecJson(Schema.toEncoded(schema))` codec.
  *
  * This is the one place a legacy-shaped document can be repaired, and why
  * `jitM` can fix things no schema decode could - an explicit `null` where a
  * `Date` is expected, a key added after the document was written. It runs
- * before any schema decode sees the document; a document it does not repair
- * still fails loudly in `codec.decode`.
+ * before any schema decode sees the document.
+ *
+ * Nothing here is lenient: a document `jitM` does not repair still fails. It
+ * fails as a typed `S.SchemaError` in a `Result` (via `S.decodeUnknownResult`)
+ * rather than by throwing, so adapters can turn it into `Effect.fail` and
+ * callers - `Repository.validateSample` in particular - can inspect it per
+ * document instead of losing the whole run to a defect.
  *
  * `_etag` is infrastructure metadata rather than part of the domain document,
  * so it is split off first and `jitM` never sees it.
- *
- * Returns `codec.decode` unchanged when there is no `jitM`; the write path,
- * which must not run migrations, keeps using `codec.decode` directly.
  */
 export const makeStoredDecode = <E extends FieldValues>(
-  codec: JsonDocumentCodec<E>,
+  schema: StoreConfig<E>["schema"],
   jitM: StoreConfig<E>["jitM"]
-): JsonDocumentCodec<E>["decode"] => {
-  if (jitM === undefined) return codec.decode
+): StoredDecode<E> => {
+  if (schema === undefined) {
+    // schemaless store: the stored document is already the Encoded document,
+    // so there is nothing to decode - only `jitM` to apply.
+    if (jitM === undefined) return Result.succeed
+    return (doc) => {
+      const { rest, _etag } = splitEtag(doc)
+      return Result.succeed(joinEtag(jitM(rest) as unknown as E, _etag))
+    }
+  }
+  const decode = S.decodeUnknownResult(jsonCodec<E>(schema))
   return (doc) => {
     const { rest, _etag } = splitEtag(doc)
     // adapters type the stored document as the Encoded persistence model, but
     // at this point it is still the raw JSON document that `jitM` is written
-    // against - and `jitM` returns JSON, which is what `codec.decode` consumes.
-    const migrated = jitM(rest) as unknown as E
-    return codec.decode(joinEtag(migrated, _etag))
+    // against - and `jitM` returns JSON, which is what the codec consumes.
+    const json = jitM === undefined ? rest : jitM(rest) as unknown as E
+    return Result.map(decode(json), (decoded) => joinEtag(decoded, _etag))
+  }
+}
+
+/**
+ * Decode a whole result set, failing fast on the first bad document.
+ *
+ * One synchronous loop and one `Result` for the batch: no Effect per document,
+ * and no allocation beyond the decoded array (plus a `Result` wrapper) on the
+ * happy path. Adapters lift the returned `Result` with `Effect.fromResult`
+ * once, at the end.
+ */
+export const decodeStoredMany = <A, B>(
+  docs: readonly A[],
+  decode: (doc: A) => Result.Result<B, S.SchemaError>
+): Result.Result<B[], S.SchemaError> => {
+  const decoded: B[] = []
+  for (const doc of docs) {
+    const result = decode(doc)
+    if (Result.isFailure(result)) return Result.fail(result.failure)
+    decoded.push(result.success)
   }
+  return Result.succeed(decoded)
 }
+
+/** Decode an optional stored document; `None` short-circuits without decoding. */
+export const decodeStoredOption = <A, B>(
+  doc: Option.Option<A>,
+  decode: (doc: A) => Result.Result<B, S.SchemaError>
+): Result.Result<Option.Option<B>, S.SchemaError> =>
+  Option.isNone(doc) ? Result.succeed(Option.none()) : Result.map(decode(doc.value), Option.some)

package/src/arbs.ts

@@ -23,13 +23,14 @@ export function generateFromArbitrary<T>(arb: S.Arbitrary<T>) {
   return generate(arb(FastCheck))
 }
 
-// Advance the seed per call: deterministic across runs, but successive calls yield different
-// samples (like `generate` advancing its shared fast-check Random).
+// Native `sampleEffect({ count: 1 })` always uses attempt 0 of the master seed (edge-biased).
+// Integer `seed + n` stayed in that bucket and collided for StringId. Mix a per-call suffix
+// so each call is a jump-before-toss, like successive `generate(rnd)` draws.
 let schemaSamples = 0
 
 export function generateFromSchema<S extends S.Constraint>(schema: S) {
   const samples = Effect.runSync(
-    Arbitrary.sampleEffect(Arbitrary.schema(schema), { count: 1, seed: seed + schemaSamples++ })
+    Arbitrary.sampleEffect(Arbitrary.schema(schema), { count: 1, seed: `${seed}:${schemaSamples++}` })
   )
   const value = samples[0]
   if (value === undefined) {

package/test/arbs-magnitude.test.ts

@@ -14,8 +14,20 @@ describe("generateFromSchema number magnitudes", () => {
     }
   })
 
+  it("keeps Finite samples realistic", () => {
+    const schema = S.Struct({ amount: S.Finite, weight: S.Finite })
+    for (let i = 0; i < 200; i++) {
+      const { amount, weight } = generateFromSchema(schema).value
+      expect(Number.isFinite(amount)).toBe(true)
+      expect(Number.isFinite(weight)).toBe(true)
+      expect(Math.max(Math.abs(amount), Math.abs(weight))).toBeLessThanOrEqual(1_000_000)
+      expect(Number.isFinite(amount * weight)).toBe(true)
+    }
+  })
+
   it("does not change the JSON Schema of the number schemas", () => {
     expect(S.toJsonSchemaDocument(S.PositiveNumber).schema).not.toHaveProperty("maximum")
     expect(S.toJsonSchemaDocument(S.NonNegativeNumber).schema).not.toHaveProperty("maximum")
+    expect(S.toJsonSchemaDocument(S.Finite).schema).not.toHaveProperty("maximum")
   })
 })

package/test/arbs.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "@effect/vitest"
+import { RequestId } from "effect-app/ids"
 import * as S from "effect-app/Schema"
 import { generateFromSchema } from "../src/arbs.js"
 
@@ -18,4 +19,23 @@ describe("generateFromSchema", () => {
       expect(S.is(schema)(generateFromSchema(schema).value)).toBe(true)
     }
   })
+
+  it("successive StringId samples are unique (count:1 jump, not attempt-0 edge strings)", () => {
+    const Item = S.Struct({ id: S.StringId, amount: S.Finite })
+    const ids = Array.from({ length: 20 }, () => generateFromSchema(Item).value.id)
+    expect(new Set(ids).size).toBe(20)
+  })
+
+  it("successive RequestId samples are unique", () => {
+    const ids = Array.from({ length: 20 }, () => generateFromSchema(RequestId).value)
+    expect(new Set(ids).size).toBe(20)
+  })
+
+  it("samples Url as https URLs", () => {
+    for (let i = 0; i < 10; i++) {
+      const url = generateFromSchema(S.Url).value
+      expect(url.startsWith("https://")).toBe(true)
+      expect(S.is(S.Url)(url)).toBe(true)
+    }
+  })
 })

package/test/repository-legacy-document.test.ts

@@ -9,8 +9,11 @@ import * as S from "effect-app/Schema"
 import { setupRequestContextFromCurrent } from "effect-app/setupRequest"
 import type { JsonRecord } from "effect-app/Store"
 import { StoreMaker } from "effect-app/Store"
+import * as Cause from "effect/Cause"
+import * as Exit from "effect/Exit"
+import * as Result from "effect/Result"
 import { describe, expect, it } from "vitest"
-import { makeJsonDocumentCodec, makeStoredDecode } from "../src/Store/jsonDocument.js"
+import { decodeStoredMany, decodeStoredOption, makeStoredDecode } from "../src/Store/jsonDocument.js"
 import { makeMemoryStoreInt } from "../src/Store/Memory.js"
 import { makeJsonLower } from "../src/Store/utils.js"
 
@@ -39,12 +42,15 @@ const LegacyDocStoreLive = (docs: readonly Record<string, unknown>[]) =>
           makeJsonLower(config)
         ),
         (store) => {
-          const decode = makeStoredDecode<any>(makeJsonDocumentCodec<any>(config?.schema), config?.jitM)
+          const decode = makeStoredDecode<any>(config?.schema, config?.jitM)
           return {
             ...store,
-            all: Effect.map(store.all, (rows) => rows.map(decode)),
-            find: (id: any) => Effect.map(store.find(id), Option.map(decode)),
-            filter: (f: any) => Effect.map(store.filter(f), (rows: any[]) => f.select ? rows : rows.map(decode))
+            all: Effect.flatMap(store.all, (rows) => Effect.fromResult(decodeStoredMany(rows, decode))),
+            find: (id: any) =>
+              Effect.flatMap(store.find(id), (doc) => Effect.fromResult(decodeStoredOption(doc, decode))),
+            filter: (f: any) =>
+              Effect.flatMap(store.filter(f), (rows: any[]) =>
+                f.select ? Effect.succeed(rows) : Effect.fromResult(decodeStoredMany(rows, decode)))
           }
         }
       )) as any
@@ -63,6 +69,12 @@ class Shop extends S.Class<Shop>("LegacyDocShop")({
 // `vatRate` was added later; stored documents from before that do not have it.
 const jitM = (json: JsonRecord): JsonRecord => "vatRate" in json ? json : { ...json, vatRate: 19 }
 
+/** does *not* repair `vatRate`, so `legacyDoc` cannot decode at the store boundary */
+const jitMThatDoesNotRepair = (json: JsonRecord): JsonRecord => ({
+  ...json,
+  updatedAt: json["updatedAt"] ?? "2024-06-03T00:00:00.000Z"
+})
+
 const legacyDoc = {
   id: "shop-legacy",
   name: "Legacy Shop",
@@ -270,53 +282,106 @@ describe("repository reads of legacy documents", () => {
   /**
    * The store boundary decode is deliberately **strict**: `jitM` is the one and
    * only place a legacy document can be repaired, and a document it does not
-   * repair must fail loudly rather than be read back half-decoded. This test
-   * pins that behaviour down on purpose - do not "fix" it by making the decode
-   * lenient.
+   * repair must fail rather than be read back half-decoded. This test pins that
+   * behaviour down on purpose - do not "fix" it by making the decode lenient.
+   *
+   * It fails as a *typed* `S.SchemaError` in the store's error channel (it used
+   * to throw out of `decodeSync` as a defect), which is what lets
+   * `validateSample` report the document instead of losing the whole run.
    */
-  it("a document jitM does not repair fails loudly at the store boundary", async () => {
-    const program = Effect
+  it("a document jitM does not repair fails as a typed SchemaError at the store boundary", () =>
+    Effect
       .gen(function*() {
+        const { make } = yield* StoreMaker
         // `vatRate` is still missing after this jitM ran: it only touches `updatedAt`
-        const repo = yield* makeRepo("LegacyDocShop", Shop, {
-          jitM: (json) => ({ ...json, updatedAt: json["updatedAt"] ?? "2024-06-03T00:00:00.000Z" })
+        const store = yield* make<"id", any>("LegacyDocShop", "id", undefined, {
+          partitionValue: () => "primary",
+          schema: Shop,
+          jitM: jitMThatDoesNotRepair
         })
 
-        return yield* repo.all
+        // `Effect.result` only catches typed failures - a defect would reject here
+        const result = yield* store.all.pipe(Effect.result)
+
+        expect(Result.isFailure(result)).toBe(true)
+        if (!Result.isFailure(result)) return
+        const failure = result.failure
+        expect(S.isSchemaError(failure)).toBe(true)
+        expect((failure as S.SchemaError)._tag).toBe("SchemaError")
+        // the strict `toCodecJson(toEncoded(schema))` decode still reports the
+        // key jitM failed to add, with the path to it
+        expect((failure as S.SchemaError).message).toContain("Missing key")
+        expect((failure as S.SchemaError).message).toContain("vatRate")
       })
       .pipe(
         Effect.provide(TestLive),
         setupRequestContextFromCurrent(),
         Effect.scoped,
         Effect.runPromise
-      )
-
-    let caught: unknown = undefined
-    try {
-      await program
-    } catch (e) {
-      caught = e
-    }
-
-    expect(caught).toBeDefined()
-    const message = caught instanceof Error ? caught.message : String(caught)
-    // the strict `toCodecJson(toEncoded(schema))` decode reports the key jitM
-    // failed to add, with the path to it
-    expect(message).toContain("Missing key")
-    expect(message).toContain("vatRate")
-  })
+      ))
+
+  /**
+   * ...and the *public* repository surface is unchanged: `Repository.find`/`all`
+   * declare only `DatabaseError`, so the store's `SchemaError` becomes a defect
+   * when the public members are produced.
+   */
+  it("the same document still dies on a public repository read", () =>
+    Effect
+      .gen(function*() {
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM: jitMThatDoesNotRepair })
+
+        const exit = yield* repo.all.pipe(Effect.exit)
+        expect(Exit.isFailure(exit)).toBe(true)
+        if (Exit.isFailure(exit)) {
+          expect(Cause.hasDies(exit.cause)).toBe(true)
+          expect(Cause.hasFails(exit.cause)).toBe(false)
+        }
+
+        // a defect is not catchable as a typed failure
+        const notCaught = yield* repo.find("shop-legacy").pipe(Effect.result, Effect.exit)
+        expect(Exit.isFailure(notCaught)).toBe(true)
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("validateSample reports a document that fails at the store boundary and keeps going", () =>
+    Effect
+      .gen(function*() {
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM: jitMThatDoesNotRepair })
+
+        const result = yield* repo.validateSample({ percentage: 1.0 })
+
+        expect(result.total).toBe(2)
+        expect(result.sampled).toBe(2)
+        // `shop-current` decodes, `shop-legacy` does not
+        expect(result.valid).toBe(1)
+        expect(result.errors).toHaveLength(1)
+        const error = result.errors[0]!
+        expect(error.id).toBe("shop-legacy")
+        expect(S.isSchemaError(error.error)).toBe(true)
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
 
   it("_etag is not visible to jitM and survives the round trip", () => {
     const seen: JsonRecord[] = []
     const decode = makeStoredDecode<any>(
-      makeJsonDocumentCodec<any>(Shop),
+      Shop,
       (json) => {
         seen.push(json)
         return { ...json, vatRate: 19 }
       }
     )
 
-    const decoded = decode({ ...legacyDoc, _etag: "etag-1" } as any)
+    const decoded = Result.getOrThrow(decode({ ...legacyDoc, _etag: "etag-1" } as any))
 
     // jitM sees the document without the infra metadata
     expect(seen).toHaveLength(1)