feat: add example code files and update docs to reference them

Author: PaulJPhilp

.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint/eslint-plugin"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-plugin/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "env": {
+    "es6": true,
+    "node": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "warn",
+      { "argsIgnorePattern": "^_" }
+    ],
+    "no-constant-condition": "off"
+  }
+}

README.md

@@ -260,12 +260,21 @@ How to test Effect code effectively, reliably, and deterministically.
 
 ## AI Coding Rules
 
-This project provides a machine-readable set of coding rules for AI-powered IDEs and coding agents.
+This project provides several machine-readable sets of coding rules, tailored for different needs and optimized for AI-powered IDEs and coding agents like Cursor or GitHub Copilot.
 
-You can find the latest rules files in the [rules directory](./rules/). These files are designed for integration with tools like Cursor, GitHub Copilot, and other AI coding assistants.
+You can find the latest rule files in the [`rules`](./rules/) directory. These are automatically generated from the content in this repository.
 
-- **rules.md**: Human-readable rules summary
-- **rules.json**: Structured rules for programmatic consumption
+### Available Formats
+
+-   **Comprehensive Rules (`rules.md`)**: A human-readable markdown file containing all patterns, guidelines, and rationale.
+-   **Compact Rules (`rules-compact.md`)**: A condensed version containing only the core rule for each pattern, designed for minimal token usage.
+-   **Structured JSON (`rules.json`)**: A machine-readable JSON file containing all rule information for programmatic use.
+-   **By Skill Level**: Detailed rules, including examples, split into separate files for each skill level.
+    -   [`beginner.md`](./rules/beginner.md)
+    -   [`intermediate.md`](./rules/intermediate.md)
+    -   [`advanced.md`](./rules/advanced.md)
+-   **By Use Case**: Detailed rules, including examples, grouped by practical application areas.
+    -   [View all use cases](./rules/by-use-case/)
 
 ---
 

bun.lock

@@ -23,19 +23,7 @@ This allows your business logic to declaratively state its dependency on a piece
 
 ## Good Example
 
-```typescript
-import { Config, Effect } from "effect";
-
-const ServerConfig = Config.all({
-  host: Config.string("HOST"),
-  port: Config.number("PORT"),
-});
-
-const program = Effect.gen(function* () {
-  const config = yield* ServerConfig;
-  yield* Effect.log(`Starting server on http://${config.host}:${config.port}`);
-});
-```
+<Example path="./src/access-config-in-context.ts" />
 
 **Explanation:**  
 By yielding the config object, you make your dependency explicit and leverage Effect's context system for testability and modularity.

content/access-config-in-context.mdx

@@ -42,41 +42,7 @@ This makes any time-dependent logic pure, deterministic, and easy to test with p
 
 This example shows a function that checks if a token is expired. Its logic depends on `Clock`, making it fully testable.
 
-```typescript
-import { Effect, Clock, Layer } from "effect";
-import { TestClock } from "effect/TestClock";
-import { describe, it, expect } from "vitest";
-
-interface Token {
-  readonly value: string;
-  readonly expiresAt: number; // UTC milliseconds
-}
-
-// This function is pure and testable because it depends on Clock
-const isTokenExpired = (token: Token): Effect.Effect<boolean, never, Clock> =>
-  Clock.currentTimeMillis.pipe(
-    Effect.map((now) => now > token.expiresAt),
-  );
-
-// --- Testing the function ---
-describe("isTokenExpired", () => {
-  const token = { value: "abc", expiresAt: 1000 };
-
-  it("should return false when the clock is before the expiry time", () =>
-    Effect.gen(function* () {
-      yield* TestClock.setTime(500); // Set virtual time
-      const isExpired = yield* isTokenExpired(token);
-      expect(isExpired).toBe(false);
-    }).pipe(Effect.provide(TestClock.layer), Effect.runPromise));
-
-  it("should return true when the clock is after the expiry time", () =>
-    Effect.gen(function* () {
-      yield* TestClock.setTime(1500); // Set virtual time
-      const isExpired = yield* isTokenExpired(token);
-      expect(isExpired).toBe(true);
-    }).pipe(Effect.provide(TestClock.layer), Effect.runPromise));
-});
-```
+<Example path="./src/accessing-current-time-with-clock.ts" />
 
 ---
 

content/accessing-current-time-with-clock.mdx

@@ -40,39 +40,7 @@ However, for tasks like validating a user's input, this is poor user experience.
 
 Using `Schema.decode` with the `allErrors: true` option demonstrates this pattern perfectly. The underlying mechanism uses `Either` to collect all parsing errors into an array instead of stopping at the first one.
 
-````typescript
-import { Effect, Schema } from "effect";
-
-const UserSchema = Schema.Struct({
-  name: Schema.String.pipe(Schema.minLength(3)),
-  email: Schema.String.pipe(Schema.pattern(/@/)),
-});
-
-const invalidInput = {
-  name: "Al", // Too short
-  email: "bob-no-at-sign.com", // Invalid pattern
-};
-
-// Use { allErrors: true } to enable error accumulation
-const decoded = Schema.decode(UserSchema)(invalidInput, { allErrors: true });
-
-const program = Effect.match(decoded, {
-  onFailure: (error) => {
-    // The error contains a tree of all validation failures
-    console.log("Validation failed with multiple errors:");
-    error.errors.forEach((e, i) => console.log(`${i + 1}. ${e.message}`));
-  },
-  onSuccess: (user) => console.log("User is valid:", user),
-});
-
-Effect.runSync(program);
-/*
-Output:
-Validation failed with multiple errors:
-1. name must be a string at least 3 character(s) long
-2. email must be a string matching the pattern /@/
-*/
-````
+`<Example path="./src/accumulate-multiple-errors-with-either.ts" />`
 
 ---
 

content/accumulate-multiple-errors-with-either.mdx

@@ -45,63 +45,7 @@ This approach is powerful because:
 
 We have a `WeatherService` that makes slow API calls. We create a `WeatherService.cached` wrapper layer that adds an in-memory cache using a `Ref` and a `Map`.
 
-```typescript
-import { Effect, Layer, Ref, Duration } from "effect";
-
-// 1. The original service definition
-class WeatherService extends Effect.Tag("WeatherService")<
-  WeatherService,
-  { readonly getForecast: (city: string) => Effect.Effect<string, "ApiError"> }
->() {}
-
-// 2. The "Live" implementation that is slow
-const WeatherServiceLive = Layer.succeed(
-  WeatherService,
-  WeatherService.of({
-    getForecast: (city) =>
-      Effect.succeed(`Sunny in ${city}`).pipe(
-        Effect.delay("2 seconds"),
-        Effect.tap(() => Effect.log(`Fetched live forecast for ${city}`)),
-      ),
-  }),
-);
-
-// 3. The Caching Wrapper Layer
-const WeatherServiceCached = Layer.effect(
-  WeatherService,
-  Effect.gen(function* () {
-    // It REQUIRES the original WeatherService
-    const underlyingService = yield* WeatherService;
-    const cache = yield* Ref.make(new Map<string, string>());
-
-    return WeatherService.of({
-      getForecast: (city) =>
-        Ref.get(cache).pipe(
-          Effect.flatMap((map) =>
-            map.has(city)
-              ? Effect.log(`Cache HIT for ${city}`).pipe(Effect.as(map.get(city)!))
-              : Effect.log(`Cache MISS for ${city}`).pipe(
-                  Effect.flatMap(() => underlyingService.getForecast(city)),
-                  Effect.tap((forecast) => Ref.update(cache, (map) => map.set(city, forecast))),
-                ),
-          ),
-        ),
-    });
-  }),
-);
-
-// 4. Compose the final layer. The wrapper is provided with the live implementation.
-const AppLayer = Layer.provide(WeatherServiceCached, WeatherServiceLive);
-
-// 5. The application logic
-const program = Effect.gen(function* () {
-  const weather = yield* WeatherService;
-  yield* weather.getForecast("London"); // First call is slow (MISS)
-  yield* weather.getForecast("London"); // Second call is instant (HIT)
-});
-
-Effect.runPromise(Effect.provide(program, AppLayer));
-```
+<Example path="./src/add-caching-by-wrapping-a-layer.ts" />
 
 ---
 

content/add-caching-by-wrapping-a-layer.mdx

@@ -47,38 +47,7 @@ This allows you to answer questions like:
 
 This example creates a counter to track how many times a user is created and a histogram to track the duration of the database operation.
 
-```typescript
-import { Effect, Metric, Duration } from "effect";
-
-// 1. Define your metrics. It's good practice to keep them in one place.
-const userRegisteredCounter = Metric.counter("users_registered_total", {
-  description: "A counter for how many users have been registered.",
-});
-
-const dbDurationHistogram = Metric.histogram(
-  "db_operation_duration_seconds",
-  Metric.Histogram.Boundaries.exponential({ start: 0.01, factor: 2, count: 10 }),
-);
-
-// 2. A simulated database call
-const saveUserToDb = Effect.succeed("user saved").pipe(
-  Effect.delay(Duration.millis(Math.random() * 100)),
-);
-
-// 3. Instrument the business logic
-const createUser = Effect.gen(function* () {
-  // Use .pipe() and Metric.trackDuration to time the operation
-  yield* saveUserToDb.pipe(Metric.trackDuration(dbDurationHistogram));
-
-  // Use Metric.increment to update the counter
-  yield* Metric.increment(userRegisteredCounter);
-
-  return { status: "success" };
-});
-
-// When run with a metrics backend, these metrics would be exported.
-Effect.runPromise(createUser);
-```
+<Example path="./src/add-custom-metrics.ts" />
 
 ---
 

content/add-custom-metrics.mdx

@@ -25,17 +25,7 @@ debug than deeply nested functional chains.
 
 ## Good Example
 
-```typescript
-import { Effect } from "effect";
-declare const step1: () => Effect.Effect<any>;
-declare const step2: (a: any) => Effect.Effect<any>;
-
-Effect.gen(function* () {
-  const a = yield* step1();
-  const b = yield* step2(a);
-  return b;
-});
-```
+<Example path="./src/avoid-long-andthen-chains.ts" />
 
 **Explanation:**  
 Generators keep sequential logic readable and easy to maintain.

content/avoid-long-andthen-chains.mdx

@@ -45,36 +45,7 @@ This makes your time-based logic pure, predictable, and easy to test.
 
 This example shows a function that creates a timestamped event. It depends on the `Clock` service, making it fully testable.
 
-```typescript
-import { Effect, Clock, Layer } from "effect";
-import { TestClock } from "effect/TestClock";
-import { describe, it, expect } from "vitest";
-
-interface Event {
-  readonly message: string;
-  readonly timestamp: number; // Store as a primitive number (UTC millis)
-}
-
-// This function is pure and testable because it depends on Clock
-const createEvent = (message: string): Effect.Effect<Event, never, Clock> =>
-  Effect.gen(function* () {
-    const timestamp = yield* Clock.currentTimeMillis;
-    return { message, timestamp };
-  });
-
-// --- Testing the function ---
-describe("createEvent", () => {
-  it("should use the time from the TestClock", () =>
-    Effect.gen(function* () {
-      // Manually set the virtual time
-      yield* TestClock.setTime(1672531200000); // Jan 1, 2023 UTC
-      const event = yield* createEvent("User logged in");
-
-      // The timestamp is predictable and testable
-      expect(event.timestamp).toBe(1672531200000);
-    }).pipe(Effect.provide(TestClock.layer), Effect.runPromise));
-});
-```
+<Example path="./src/beyond-the-date-type.ts" />
 
 ---