effect-app 4.0.0-beta.27 → 4.0.0-beta.272

package/src/Model/Repository/service.ts

@@ -0,0 +1,676 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type * as Scope from "effect/Scope"
+import type { DatabaseError, InvalidStateError, NotFoundError, OptimisticConcurrencyException } from "../../client/errors.ts"
+import type * as Effect from "../../Effect.ts"
+import type * as Option from "../../Option.ts"
+import type * as S from "../../Schema.ts"
+import type { NonNegativeInt } from "../../Schema/numbers.ts"
+import type { FieldValues, IsNever, ResolveFirstLevel } from "../filter/types.ts"
+import type { QAll, Query, QueryProjection, RawQuery } from "../query.ts"
+import type { Mapped } from "./legacy.ts"
+import type { ValidationResult } from "./validation.ts"
+
+/**
+ * Event emitted by a repository's ChangeFeed.
+ *
+ * Tuple shape: `[items, op, namespace]` — `namespace` is the `storeId`
+ * context value at publish time (defaults to `"primary"`).
+ */
+export type ChangeFeedEvent<T> = readonly [items: T[], op: "save" | "remove", namespace: string]
+
+/**
+ * Synchronous broadcast channel for repository change events.
+ *
+ * `publish` only completes after every matching handler's Effect has
+ * finished — callers must await all handlers before continuing. Subscribers
+ * can target a single namespace via `options.namespace`, or omit it to
+ * receive events from every namespace (wildcard).
+ *
+ * Handlers are auto-removed when the subscriber's Scope closes; the full
+ * handler set is cleared when the repository's own scope closes.
+ */
+export interface ChangeFeed<T> {
+  readonly publish: (evt: [T[], "save" | "remove"]) => Effect.Effect<void>
+  readonly subscribe: (
+    handler: (evt: ChangeFeedEvent<T>) => Effect.Effect<void>,
+    options?: { readonly namespace?: string }
+  ) => Effect.Effect<void, never, Scope.Scope>
+}
+
+export interface Repository<
+  T,
+  Encoded extends FieldValues,
+  Evt,
+  ItemType extends string,
+  IdKey extends keyof T,
+  RSchema,
+  RPublish,
+  RProvided = never
+> {
+  readonly itemType: ItemType
+  readonly idKey: IdKey
+  readonly find: (id: T[IdKey]) => Effect.Effect<Option.Option<T>, DatabaseError, RSchema>
+  readonly all: Effect.Effect<T[], DatabaseError, RSchema>
+  readonly saveAndPublish: (
+    items: Iterable<T>,
+    events?: Iterable<Evt>
+  ) => Effect.Effect<void, InvalidStateError | OptimisticConcurrencyException | DatabaseError, RSchema | RPublish>
+  readonly changeFeed: ChangeFeed<T>
+  readonly removeAndPublish: (
+    items: Iterable<T>,
+    events?: Iterable<Evt>
+  ) => Effect.Effect<void, DatabaseError, RSchema | RPublish>
+
+  readonly removeById: (
+    idOrIds: T[IdKey] | ReadonlyArray<T[IdKey]>
+  ) => Effect.Effect<void, DatabaseError, RSchema>
+
+  readonly queryRaw: <T, Out, R>(
+    schema: S.Codec<T, Out, R>,
+    raw: RawQuery<Encoded, Out>
+  ) => Effect.Effect<readonly T[], S.SchemaError | DatabaseError, R>
+
+  /**
+   * Explicitly seed a namespace. Primary is seeded eagerly on initialization.
+   * Non-primary namespaces must be seeded explicitly before use.
+   */
+  readonly seedNamespace: (namespace: string) => Effect.Effect<void, DatabaseError>
+
+  readonly query: {
+    // ending with projection
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      E extends boolean = false
+    >(
+      q: (
+        initial: Query<Encoded>
+      ) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (
+        _: $A
+      ) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (
+        _: $B
+      ) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (
+        _: $C
+      ) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (
+        _: $D
+      ) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (_: $G) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      $H = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (_: $G) => $H,
+      q9: (_: $H) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      A,
+      R,
+      From extends FieldValues,
+      TType extends "one" | "many" | "count" = "many",
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      $H = never,
+      $I = never,
+      E extends boolean = false
+    >(
+      q1: (
+        initial: Query<Encoded>
+      ) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (_: $G) => $H,
+      q9: (_: $H) => $I,
+      q10: (_: $I) => QueryProjection<From extends Encoded ? From : never, A, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? readonly A[] : TType extends "count" ? NonNegativeInt : A,
+      | (TType extends "many" ? never : NotFoundError<ItemType>)
+      | (TType extends "count" ? never : S.SchemaError)
+      | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+
+    // ending with generic query
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      E extends boolean = false
+    >(
+      q: (initial: Query<Encoded>) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (
+        _: $A
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (
+        _: $A
+      ) => $B,
+      q3: (
+        _: $B
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (
+        _: $C
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (
+        _: $D
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (
+        _: $E
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (
+        _: $F
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined> : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (
+        _: $G
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined>
+        : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      $H = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (_: $G) => $H,
+      q9: (
+        _: $H
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined>
+        : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+    <
+      R = never,
+      TType extends "one" | "many" = "many",
+      EncodedRefined extends Encoded = Encoded,
+      $A = never,
+      $B = never,
+      $C = never,
+      $D = never,
+      $E = never,
+      $F = never,
+      $G = never,
+      $H = never,
+      $I = never,
+      E extends boolean = false
+    >(
+      q1: (initial: Query<Encoded>) => $A,
+      q2: (_: $A) => $B,
+      q3: (_: $B) => $C,
+      q4: (_: $C) => $D,
+      q5: (_: $D) => $E,
+      q6: (_: $E) => $F,
+      q7: (_: $F) => $G,
+      q8: (_: $G) => $H,
+      q9: (_: $H) => $I,
+      q10: (
+        _: $I
+      ) => QAll<Encoded, EncodedRefined, RefineTHelper<T, EncodedRefined>, R, TType, E>
+    ): Effect.Effect<
+      TType extends "many" ? DistributeQueryIfExclusiveOnArray<E, T, EncodedRefined>
+        : RefineTHelper<T, EncodedRefined>,
+      (TType extends "many" ? never : NotFoundError<ItemType>) | DatabaseError,
+      Exclude<R, RProvided> | RSchema
+    >
+  }
+
+  /** @deprecated use query */
+  readonly mapped: Mapped<Encoded>
+
+  /**
+   * Validates a random sample of repository items by applying jitM and schema decode.
+   * Useful for testing that migrations and schema changes work correctly on existing data.
+   */
+  readonly validateSample: (options?: {
+    /** percentage of items to sample (0.0-1.0), default 0.1 (10%) */
+    percentage?: number
+    /** optional maximum number of items to sample */
+    maxItems?: number
+  }) => Effect.Effect<ValidationResult, DatabaseError, RSchema>
+}
+
+type DistributeQueryIfExclusiveOnArray<Exclusive extends boolean, T, EncodedRefined> = [Exclusive] extends [true]
+  ? T extends any ? RefineTHelper<T, EncodedRefined> extends infer R ? IsNever<R> extends true ? never
+      : readonly R[]
+    : never
+  : never
+  : readonly RefineTHelper<T, EncodedRefined>[]
+
+type NullableRefined<T, EncodedRefined> = {
+  // EncodedRefined may be a union, so if you just keyof you'll get just common keys
+  // p.s. NullableRefined is homomorphic in T so it distributes itself over T
+  [k in keyof T]: [null] extends [T[k]] ? [null] extends [Extract<EncodedRefined, { [j in k]: any }>[k]] ? T[k]
+    : Exclude<T[k], null>
+    : T[k]
+}
+
+// for DX purposes
+type ShouldRecursiveExtractTagged<T, EncodedRefined> = true extends {
+  [k in keyof T]: "_tag" extends keyof T[k]
+    ? k extends keyof EncodedRefined ? "_tag" extends keyof EncodedRefined[k] ? true
+      : false
+    : false
+    : false
+}[keyof T] ? true
+  : false
+
+// support is not 100% but we have to make compromises
+type RecursiveExtractTagged<T, EncodedRefined> = ShouldRecursiveExtractTagged<T, EncodedRefined> extends true ? {
+    [k in keyof T]: "_tag" extends keyof T[k]
+      ? k extends keyof EncodedRefined ? "_tag" extends keyof EncodedRefined[k] ? ExtractTagged<T[k], EncodedRefined[k]>
+        : T[k]
+      : T[k]
+      : T[k]
+  }
+  : T
+
+type ExtractTagged_<T, EncodedRefined> = EncodedRefined extends { _tag: string }
+  ? T extends { _tag: string } ? Extract<T, { _tag: EncodedRefined["_tag"] }>
+  : T
+  : T
+
+type ExtractTagged<T, EncodedRefined> = ExtractTagged_<T, EncodedRefined> extends infer R
+  ? RecursiveExtractTagged<RecusiveExtractIded<R, EncodedRefined>, EncodedRefined>
+  : never
+
+type ShouldRecursiveExtractIded<T, EncodedRefined> = true extends {
+  [k in keyof T]: "id" extends keyof T[k] ? k extends keyof EncodedRefined ? "id" extends keyof EncodedRefined[k] ? true
+      : false
+    : false
+    : false
+}[keyof T] ? true
+  : false
+
+type RecusiveExtractIded<T, EncodedRefined> = ShouldRecursiveExtractIded<T, EncodedRefined> extends true ? {
+    [k in keyof T]: "id" extends keyof T[k]
+      ? k extends keyof EncodedRefined ? "id" extends keyof EncodedRefined[k] ? ExtractIded<T[k], EncodedRefined[k]>
+        : T[k]
+      : T[k]
+      : T[k]
+  }
+  : T
+
+type ExtractIded_<T, EncodedRefined> = EncodedRefined extends { id: string }
+  ? T extends { id: string } ? Extract<T, { id: EncodedRefined["id"] }>
+  : T
+  : T
+
+type ExtractIded<T, EncodedRefined> = ExtractIded_<T, EncodedRefined> extends infer R
+  ? RecusiveExtractIded<RecursiveExtractTagged<R, EncodedRefined>, EncodedRefined>
+  : never
+
+export type RefineTHelper<T, EncodedRefined> = ResolveFirstLevel<
+  NullableRefined<
+    ExtractIded<ExtractTagged<T, EncodedRefined>, EncodedRefined>,
+    EncodedRefined
+  >
+>

package/src/Model/Repository/validation.ts

@@ -0,0 +1,31 @@
+import * as S from "../../Schema.ts"
+import { NonNegativeInt } from "../../Schema.ts"
+
+/**
+ * Represents a single validation error when decoding a repository item.
+ * Contains full context for debugging: raw data, jitM result, and decode error.
+ */
+export class ValidationError extends S.Opaque<ValidationError>()(S.Struct({
+  /** the id of the item that failed validation */
+  id: S.Unknown,
+  /** the raw data from the database before jitM */
+  rawData: S.Unknown,
+  /** the data after applying jitM transformation */
+  jitMResult: S.Unknown,
+  /** the S.SchemaError from schema decode */
+  error: S.Unknown
+})) {}
+
+/**
+ * Result of validating a sample of repository items.
+ */
+export class ValidationResult extends S.Opaque<ValidationResult>()(S.Struct({
+  /** total number of items in the repository */
+  total: NonNegativeInt,
+  /** number of items that were sampled for validation */
+  sampled: NonNegativeInt,
+  /** number of items that passed validation */
+  valid: NonNegativeInt,
+  /** list of validation errors with full context */
+  errors: S.Array(ValidationError)
+})) {}