@danieljvdm/dev-kit 0.6.0 → 0.7.0

package/skills/effect-ts/references/audit-services.md

@@ -44,17 +44,17 @@ Enumerate source and test files, then find:
 
 Record one row per discovered service or candidate:
 
-| Field | Question |
-| --- | --- |
-| Owner | Which module owns the capability's meaning? |
-| Contract | Where are its interface and tag? |
-| Construction | Does construction yield every runtime dependency? |
-| Production | Who owns the concrete implementation and Layer choice? |
-| Tests | Does it have an intentional and honest substitute strategy? |
-| Consumers | Are capabilities yielded or drilled as values? |
-| Requirements | Do requirements remain visible to the composition root? |
-| Type boundary | Who owns decoding, narrowing, and error translation? |
-| Verdict | Keep, deepen, relocate, merge, remove, or create? |
+| Field         | Question                                                    |
+| ------------- | ----------------------------------------------------------- |
+| Owner         | Which module owns the capability's meaning?                 |
+| Contract      | Where are its interface and tag?                            |
+| Construction  | Does construction yield every runtime dependency?           |
+| Production    | Who owns the concrete implementation and Layer choice?      |
+| Tests         | Does it have an intentional and honest substitute strategy? |
+| Consumers     | Are capabilities yielded or drilled as values?              |
+| Requirements  | Do requirements remain visible to the composition root?     |
+| Type boundary | Who owns decoding, narrowing, and error translation?        |
+| Verdict       | Keep, deepen, relocate, merge, remove, or create?           |
 
 Build a companion type-safety inventory using
 [`guide-type-safety-and-boundaries.md`](guide-type-safety-and-boundaries.md).

package/skills/effect-ts/references/guide-effect.md

@@ -47,11 +47,11 @@ The dominant usage pattern is:
 For reusable effectful operations, prefer `Effect.fn`.
 
 ```ts
-import { Effect } from "effect"
+import { Effect } from "effect";
 
-const loadUser = Effect.fn("loadUser")(function*(userId: string) {
-  return { id: userId, name: "Ada" }
-})
+const loadUser = Effect.fn("loadUser")(function* (userId: string) {
+  return { id: userId, name: "Ada" };
+});
 ```
 
 Use `Effect.fn` when:
@@ -73,12 +73,12 @@ Repo examples:
 Use `Effect.gen` for orchestration and sequential workflows, especially when there are multiple `yield*` steps.
 
 ```ts
-const program = Effect.gen(function*() {
-  const config = yield* Config
-  const repo = yield* UserRepo
-  const user = yield* repo.getById("u_123")
-  return { config, user }
-})
+const program = Effect.gen(function* () {
+  const config = yield* Config;
+  const repo = yield* UserRepo;
+  const user = yield* repo.getById("u_123");
+  return { config, user };
+});
 ```
 
 Use `Effect.gen` when:
@@ -103,15 +103,15 @@ Use this rule:
 Good split:
 
 ```ts
-const loadUser = Effect.fn("loadUser")(function*(userId: string) {
-  const repo = yield* UserRepo
-  return yield* repo.getById(userId)
-})
-
-const program = Effect.gen(function*() {
-  const user = yield* loadUser("u_123")
-  yield* Effect.logInfo("loaded user", user)
-})
+const loadUser = Effect.fn("loadUser")(function* (userId: string) {
+  const repo = yield* UserRepo;
+  return yield* repo.getById(userId);
+});
+
+const program = Effect.gen(function* () {
+  const user = yield* loadUser("u_123");
+  yield* Effect.logInfo("loaded user", user);
+});
 ```
 
 ## `Effect.fnUntraced` Is An Escape Hatch
@@ -127,17 +127,17 @@ Use it only when:
 If the only goal is to avoid an explicit named span, prefer:
 
 ```ts
-const normalizeUser = Effect.fn(function*(input: string) {
-  return input.trim().toLowerCase()
-})
+const normalizeUser = Effect.fn(function* (input: string) {
+  return input.trim().toLowerCase();
+});
 ```
 
 Instead of:
 
 ```ts
-const normalizeUser = Effect.fnUntraced(function*(input: string) {
-  return input.trim().toLowerCase()
-})
+const normalizeUser = Effect.fnUntraced(function* (input: string) {
+  return input.trim().toLowerCase();
+});
 ```
 
 ## Constructor Functions
@@ -149,7 +149,7 @@ The repo uses constructor functions very deliberately.
 Use for pure successful values.
 
 ```ts
-const ok = Effect.succeed(42)
+const ok = Effect.succeed(42);
 ```
 
 ### `Effect.fail`
@@ -157,7 +157,7 @@ const ok = Effect.succeed(42)
 Use for expected typed failures.
 
 ```ts
-const notFound = Effect.fail(UserNotFound.make({ userId: "u_123" }))
+const notFound = Effect.fail(UserNotFound.make({ userId: "u_123" }));
 ```
 
 ### `Effect.sync`
@@ -165,7 +165,7 @@ const notFound = Effect.fail(UserNotFound.make({ userId: "u_123" }))
 Use for synchronous side effects or pure synchronous construction that should live inside `Effect`.
 
 ```ts
-const buildConfig = Effect.sync(() => ({ retries: 3 }))
+const buildConfig = Effect.sync(() => ({ retries: 3 }));
 ```
 
 ### `Effect.try`
@@ -173,17 +173,17 @@ const buildConfig = Effect.sync(() => ({ retries: 3 }))
 Use for synchronous code that may throw.
 
 ```ts
-import { Effect, Schema } from "effect"
+import { Effect, Schema } from "effect";
 
 class ParseError extends Schema.TaggedErrorClass<ParseError>()("ParseError", {
-  cause: Schema.Defect()
+  cause: Schema.Defect(),
 }) {}
 
 const parseJson = (input: string) =>
   Effect.try({
     try: () => JSON.parse(input),
-    catch: (cause) => ParseError.make({ cause })
-  })
+    catch: (cause) => ParseError.make({ cause }),
+  });
 ```
 
 ### `Effect.tryPromise`
@@ -194,17 +194,17 @@ opaque cause when it is diagnostically useful. Compose Effect-native APIs
 directly instead of converting them through Promise.
 
 ```ts
-import { Effect, Schema } from "effect"
+import { Effect, Schema } from "effect";
 
 class FetchError extends Schema.TaggedErrorClass<FetchError>()("FetchError", {
-  cause: Schema.Defect()
+  cause: Schema.Defect(),
 }) {}
 
 const fetchText = (url: string) =>
   Effect.tryPromise({
     try: () => fetch(url).then((response) => response.text()),
-    catch: (cause) => FetchError.make({ cause })
-  })
+    catch: (cause) => FetchError.make({ cause }),
+  });
 ```
 
 Preferred rule:
@@ -224,9 +224,7 @@ The repo uses `map`, `flatMap`, and `tap` constantly for small local transformat
 Use to transform successful values.
 
 ```ts
-const userName = loadUser("u_123").pipe(
-  Effect.map((user) => user.name)
-)
+const userName = loadUser("u_123").pipe(Effect.map((user) => user.name));
 ```
 
 ### `Effect.flatMap`
@@ -234,9 +232,7 @@ const userName = loadUser("u_123").pipe(
 Use when the next step returns another `Effect`.
 
 ```ts
-const result = loadUser("u_123").pipe(
-  Effect.flatMap((user) => saveAudit(user.id))
-)
+const result = loadUser("u_123").pipe(Effect.flatMap((user) => saveAudit(user.id)));
 ```
 
 ### `Effect.tap`
@@ -245,8 +241,8 @@ Use for side effects that should preserve the main value.
 
 ```ts
 const result = loadUser("u_123").pipe(
-  Effect.tap((user) => Effect.logDebug("loaded user", { userId: user.id }))
-)
+  Effect.tap((user) => Effect.logDebug("loaded user", { userId: user.id })),
+);
 ```
 
 Preferred rule:
@@ -264,27 +260,23 @@ Repo style is:
 ### Access services in implementations
 
 ```ts
-const loadUser = Effect.fn("loadUser")(function*(userId: string) {
-  const repo = yield* UserRepo
-  return yield* repo.getById(userId)
-})
+const loadUser = Effect.fn("loadUser")(function* (userId: string) {
+  const repo = yield* UserRepo;
+  return yield* repo.getById(userId);
+});
 ```
 
 or:
 
 ```ts
 const loadUser = (userId: string) =>
-  Effect.service(UserRepo).pipe(
-    Effect.flatMap((repo) => repo.getById(userId))
-  )
+  Effect.service(UserRepo).pipe(Effect.flatMap((repo) => repo.getById(userId)));
 ```
 
 ### Provide at the edge
 
 ```ts
-const program = loadUser("u_123").pipe(
-  Effect.provide(AppLayer)
-)
+const program = loadUser("u_123").pipe(Effect.provide(AppLayer));
 ```
 
 Use `provideService` and `provideServiceEffect` for targeted overrides, especially in tests or framework boundaries.
@@ -309,9 +301,7 @@ Common repo patterns:
 Use for targeted typed recovery.
 
 ```ts
-const safe = loadUser("u_123").pipe(
-  Effect.catchTag("UserNotFound", () => Effect.succeed(null))
-)
+const safe = loadUser("u_123").pipe(Effect.catchTag("UserNotFound", () => Effect.succeed(null)));
 ```
 
 ### `Effect.match`
@@ -322,9 +312,9 @@ Use when the caller wants a value either way.
 const result = loadUser("u_123").pipe(
   Effect.match({
     onFailure: () => null,
-    onSuccess: (user) => user
-  })
-)
+    onSuccess: (user) => user,
+  }),
+);
 ```
 
 For deeper guidance, see `./references/guide-error-handling.md`.
@@ -338,10 +328,7 @@ One of the strongest repo patterns is explicit resource ownership.
 Use for resources that must be cleaned up.
 
 ```ts
-const connection = Effect.acquireRelease(
-  openConnection,
-  (conn) => closeConnection(conn)
-)
+const connection = Effect.acquireRelease(openConnection, (conn) => closeConnection(conn));
 ```
 
 ### `Effect.scoped`
@@ -350,11 +337,11 @@ Use when a workflow consumes scoped resources and should tie cleanup to scope li
 
 ```ts
 const program = Effect.scoped(
-  Effect.gen(function*() {
-    const conn = yield* connection
-    return yield* conn.query("select 1")
-  })
-)
+  Effect.gen(function* () {
+    const conn = yield* connection;
+    return yield* conn.query("select 1");
+  }),
+);
 ```
 
 Repo examples:

package/skills/effect-ts/references/guide-error-handling.md

@@ -59,34 +59,34 @@ Repo references:
 Example:
 
 ```ts
-import { Effect, Schema } from "effect"
+import { Effect, Schema } from "effect";
 
-class InvalidPayload extends Schema.TaggedErrorClass<InvalidPayload>()(
-  "InvalidPayload",
-  {
-    field: Schema.String,
-    reason: Schema.String
-  }
-) {}
+class InvalidPayload extends Schema.TaggedErrorClass<InvalidPayload>()("InvalidPayload", {
+  field: Schema.String,
+  reason: Schema.String,
+}) {}
 
 const validate = Effect.fail(
   InvalidPayload.make({
     field: "email",
-    reason: "missing"
-  })
-)
+    reason: "missing",
+  }),
+);
 ```
 
 Expected application and service failures belong in the typed error channel.
 In generators, use an explicit control-flow exit when failing:
 
 ```ts
-return yield* Effect.fail(
-  InvalidPayload.make({
-    field: "email",
-    reason: "missing"
-  })
-)
+return (
+  yield *
+  Effect.fail(
+    InvalidPayload.make({
+      field: "email",
+      reason: "missing",
+    }),
+  )
+);
 ```
 
 Use this when:
@@ -128,18 +128,17 @@ Repo reference:
 Example:
 
 ```ts
-import { Data, Effect } from "effect"
+import { Data, Effect } from "effect";
 
 class UserNotFound extends Data.TaggedError("UserNotFound")<{
-  readonly userId: string
+  readonly userId: string;
 }> {}
 
-const loadUser = (userId: string) =>
-  Effect.fail(new UserNotFound({ userId }))
+const loadUser = (userId: string) => Effect.fail(new UserNotFound({ userId }));
 
-const program = Effect.gen(function*() {
-  yield* loadUser("u_123")
-})
+const program = Effect.gen(function* () {
+  yield* loadUser("u_123");
+});
 ```
 
 ## When To Prefer `Data.TaggedError` vs `Schema.TaggedErrorClass`
@@ -173,14 +172,14 @@ Repo references:
 Example:
 
 ```ts
-import { Effect, Schema } from "effect"
+import { Effect, Schema } from "effect";
 
 const UserPayload = Schema.Struct({
   id: Schema.String,
-  email: Schema.String
-})
+  email: Schema.String,
+});
 
-const decodeUser = Schema.decodeUnknownEffect(UserPayload)
+const decodeUser = Schema.decodeUnknownEffect(UserPayload);
 ```
 
 This gives you:
@@ -195,23 +194,23 @@ For application code, it is often better to convert `SchemaError` into a domain
 Example:
 
 ```ts
-import { Data, Effect, Schema } from "effect"
+import { Data, Effect, Schema } from "effect";
 
 class InvalidRequestBody extends Data.TaggedError("InvalidRequestBody")<{
-  readonly message: string
+  readonly message: string;
 }> {}
 
 const UserPayload = Schema.Struct({
   id: Schema.String,
-  email: Schema.String
-})
+  email: Schema.String,
+});
 
 const decodeUser = (input: unknown) =>
   Schema.decodeUnknownEffect(UserPayload)(input).pipe(
     Effect.catchTag("SchemaError", (error) =>
-      Effect.fail(new InvalidRequestBody({ message: error.message }))
-    )
-  )
+      Effect.fail(new InvalidRequestBody({ message: error.message })),
+    ),
+  );
 ```
 
 Why:
@@ -262,38 +261,32 @@ Prefer using:
 Example:
 
 ```ts
-import { Effect, Schema } from "effect"
+import { Effect, Schema } from "effect";
 
-class TodoStorageError extends Schema.TaggedErrorClass<TodoStorageError>()(
-  "TodoStorageError",
-  {
-    operation: Schema.String,
-    cause: Schema.Defect()
-  }
-) {}
+class TodoStorageError extends Schema.TaggedErrorClass<TodoStorageError>()("TodoStorageError", {
+  operation: Schema.String,
+  cause: Schema.Defect(),
+}) {}
 
 const makeStorageError = (operation: string) => (cause: unknown) =>
   TodoStorageError.make({
     operation,
-    cause
-  })
+    cause,
+  });
 
 const loadTodo = (id: number) =>
   Effect.try({
     try: () => someLibraryCall(id),
-    catch: makeStorageError("loadTodo")
-  })
+    catch: makeStorageError("loadTodo"),
+  });
 ```
 
 When stack preservation matters in the encoded schema, prefer:
 
 ```ts
-class WorkerFailure extends Schema.TaggedErrorClass<WorkerFailure>()(
-  "WorkerFailure",
-  {
-    cause: Schema.Defect({ includeStack: true })
-  }
-) {}
+class WorkerFailure extends Schema.TaggedErrorClass<WorkerFailure>()("WorkerFailure", {
+  cause: Schema.Defect({ includeStack: true }),
+}) {}
 ```
 
 ### Why This Is Preferred
@@ -332,8 +325,8 @@ Bad:
 const loadTodo = (id: number) =>
   Effect.try({
     try: () => someLibraryCall(id),
-    catch: (cause) => cause as Error
-  })
+    catch: (cause) => cause as Error,
+  });
 ```
 
 Why this is bad:
@@ -373,10 +366,8 @@ Example:
 
 ```ts
 const recovered = program.pipe(
-  Effect.catchTag("UserNotFound", (error) =>
-    Effect.succeed({ id: error.userId, guest: true })
-  )
-)
+  Effect.catchTag("UserNotFound", (error) => Effect.succeed({ id: error.userId, guest: true })),
+);
 ```
 
 ### Handle several tagged errors with `Effect.catchTags`
@@ -387,9 +378,9 @@ Use `catchTags` when multiple domain errors should be handled together.
 const recovered = program.pipe(
   Effect.catchTags({
     UserNotFound: () => Effect.succeed(null),
-    InvalidPayload: (error) => Effect.succeed({ error: error.reason })
-  })
-)
+    InvalidPayload: (error) => Effect.succeed({ error: error.reason }),
+  }),
+);
 ```
 
 ### Handle predicate-based subsets with `Effect.catchIf`
@@ -404,9 +395,9 @@ Use `match` when you want to fully fold the typed error channel into a success v
 const outcome = program.pipe(
   Effect.match({
     onFailure: (error) => ({ ok: false as const, error }),
-    onSuccess: (value) => ({ ok: true as const, value })
-  })
-)
+    onSuccess: (value) => ({ ok: true as const, value }),
+  }),
+);
 ```
 
 ## Handling Defects
@@ -439,17 +430,17 @@ Use defects for:
 Use `sandbox` to expose `Cause<E>` in the error channel.
 
 ```ts
-import { Cause, Effect } from "effect"
+import { Cause, Effect } from "effect";
 
 const diagnosed = program.pipe(
   Effect.sandbox,
   Effect.catchCause((cause) => {
     if (Cause.hasDies(cause)) {
-      return Effect.succeed("defect")
+      return Effect.succeed("defect");
     }
-    return Effect.failCause(cause)
-  })
-)
+    return Effect.failCause(cause);
+  }),
+);
 ```
 
 Use `matchCause` or `matchCauseEffect` when you need to distinguish:
@@ -503,11 +494,11 @@ Interrupts signal that the fiber should stop. They should not usually be transla
 If interrupted work needs special cleanup, use `onInterrupt`.
 
 ```ts
-import { Console, Effect } from "effect"
+import { Console, Effect } from "effect";
 
 const program = longRunningTask.pipe(
-  Effect.onInterrupt(() => Console.log("cleaning up after interrupt"))
-)
+  Effect.onInterrupt(() => Console.log("cleaning up after interrupt")),
+);
 ```
 
 ### Use `Cause` inspection when interrupts must be distinguished