@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/effect/effect-best-practices/references/schema-patterns.md

@@ -0,0 +1,353 @@
+# Schema Patterns
+
+## Branded Types for IDs
+
+**Always brand entity IDs** to prevent accidentally passing the wrong ID type:
+
+```typescript
+import { Schema } from "effect"
+
+// Entity IDs - always branded with namespace
+export const UserId = Schema.UUID.pipe(Schema.brand("@App/UserId"))
+export type UserId = Schema.Schema.Type<typeof UserId>
+
+export const OrganizationId = Schema.UUID.pipe(Schema.brand("@App/OrganizationId"))
+export type OrganizationId = Schema.Schema.Type<typeof OrganizationId>
+
+export const OrderId = Schema.UUID.pipe(Schema.brand("@App/OrderId"))
+export type OrderId = Schema.Schema.Type<typeof OrderId>
+
+export const ProductId = Schema.UUID.pipe(Schema.brand("@App/ProductId"))
+export type ProductId = Schema.Schema.Type<typeof ProductId>
+```
+
+### Branding Convention
+
+Use `@Namespace/EntityName` format:
+- `@App/UserId` - Main application entities
+- `@Billing/InvoiceId` - Billing domain entities
+- `@External/StripeCustomerId` - External system IDs
+
+### Creating Branded Values
+
+```typescript
+// From string (validates UUID format)
+const userId = Schema.decodeSync(UserId)("123e4567-e89b-12d3-a456-426614174000")
+
+// Generate new ID
+const newUserId = UserId.make(crypto.randomUUID())
+
+// Type error - can't mix ID types
+const order = yield* orderService.findById(userId) // Error: UserId is not OrderId
+```
+
+### When NOT to Brand
+
+Don't brand simple strings that don't need type safety:
+
+```typescript
+// NOT branded - acceptable
+export const Url = Schema.String
+export const FilePath = Schema.String
+export const EmailAddress = Schema.String.pipe(Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/))
+
+// These don't need branding because:
+// 1. They don't cross service boundaries in ways that could be confused
+// 2. They're typically validated by format, not by type
+```
+
+## Schema.Struct for Domain Types
+
+**Prefer Schema.Struct** over TypeScript interfaces for domain types:
+
+```typescript
+// CORRECT - Schema.Struct
+export const User = Schema.Struct({
+    id: UserId,
+    email: Schema.String,
+    name: Schema.String,
+    organizationId: OrganizationId,
+    role: Schema.Literal("admin", "member", "viewer"),
+    createdAt: Schema.DateTimeUtc,
+    updatedAt: Schema.DateTimeUtc,
+})
+export type User = Schema.Schema.Type<typeof User>
+
+// Can derive encoded type for database/API
+export type UserEncoded = Schema.Schema.Encoded<typeof User>
+```
+
+### Input Types for Mutations
+
+```typescript
+export const CreateUserInput = Schema.Struct({
+    email: Schema.String.pipe(
+        Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
+        Schema.annotations({ description: "Valid email address" }),
+    ),
+    name: Schema.String.pipe(
+        Schema.minLength(1),
+        Schema.maxLength(100),
+    ),
+    organizationId: OrganizationId,
+    role: Schema.optionalWith(
+        Schema.Literal("admin", "member", "viewer"),
+        { default: () => "member" as const }
+    ),
+})
+export type CreateUserInput = Schema.Schema.Type<typeof CreateUserInput>
+
+export const UpdateUserInput = Schema.Struct({
+    name: Schema.optional(Schema.String.pipe(Schema.minLength(1))),
+    role: Schema.optional(Schema.Literal("admin", "member", "viewer")),
+})
+export type UpdateUserInput = Schema.Schema.Type<typeof UpdateUserInput>
+```
+
+## Schema.transform and transformOrFail
+
+**Use transforms** instead of manual parsing:
+
+```typescript
+// Transform string to Date
+export const DateFromString = Schema.transform(
+    Schema.String,
+    Schema.DateTimeUtc,
+    {
+        decode: (s) => new Date(s),
+        encode: (d) => d.toISOString(),
+    }
+)
+
+// Transform with validation (can fail)
+export const PositiveNumber = Schema.transformOrFail(
+    Schema.Number,
+    Schema.Number.pipe(Schema.brand("PositiveNumber")),
+    {
+        decode: (n, _, ast) =>
+            n > 0
+                ? ParseResult.succeed(n as Schema.Schema.Type<typeof PositiveNumber>)
+                : ParseResult.fail(new ParseResult.Type(ast, n, "Must be positive")),
+        encode: ParseResult.succeed,
+    }
+)
+```
+
+### Common Transforms
+
+```typescript
+// JSON string to object
+export const JsonFromString = <A, I>(schema: Schema.Schema<A, I>) =>
+    Schema.transform(
+        Schema.String,
+        schema,
+        {
+            decode: (s) => JSON.parse(s),
+            encode: (a) => JSON.stringify(a),
+        }
+    )
+
+// Comma-separated string to array
+export const CommaSeparatedList = Schema.transform(
+    Schema.String,
+    Schema.Array(Schema.String),
+    {
+        decode: (s) => s.split(",").map((x) => x.trim()).filter(Boolean),
+        encode: (arr) => arr.join(","),
+    }
+)
+
+// Cents to dollars
+export const DollarsFromCents = Schema.transform(
+    Schema.Number.pipe(Schema.int()),
+    Schema.Number,
+    {
+        decode: (cents) => cents / 100,
+        encode: (dollars) => Math.round(dollars * 100),
+    }
+)
+```
+
+## Schema.Class for Entities with Methods
+
+Use `Schema.Class` when entities need methods:
+
+```typescript
+export class User extends Schema.Class<User>("User")({
+    id: UserId,
+    email: Schema.String,
+    name: Schema.String,
+    role: Schema.Literal("admin", "member", "viewer"),
+    createdAt: Schema.DateTimeUtc,
+}) {
+    get isAdmin(): boolean {
+        return this.role === "admin"
+    }
+
+    get displayName(): string {
+        return this.name || this.email.split("@")[0]
+    }
+
+    canAccessResource(resource: Resource): boolean {
+        if (this.isAdmin) return true
+        return resource.ownerId === this.id
+    }
+}
+
+// Usage
+const user = new User({
+    id: UserId.make(crypto.randomUUID()),
+    email: "alice@example.com",
+    name: "Alice",
+    role: "member",
+    createdAt: new Date(),
+})
+
+console.log(user.displayName) // "Alice"
+console.log(user.isAdmin) // false
+```
+
+## Schema.annotations
+
+Add annotations for documentation and validation messages:
+
+```typescript
+export const CreateOrderInput = Schema.Struct({
+    productId: ProductId.pipe(
+        Schema.annotations({ description: "The product to order" }),
+    ),
+    quantity: Schema.Number.pipe(
+        Schema.int(),
+        Schema.positive(),
+        Schema.annotations({
+            description: "Number of items to order",
+            examples: [1, 5, 10],
+        }),
+    ),
+    shippingAddress: Schema.Struct({
+        line1: Schema.String.pipe(Schema.annotations({ description: "Street address" })),
+        line2: Schema.optional(Schema.String),
+        city: Schema.String,
+        state: Schema.String.pipe(Schema.length(2)),
+        zip: Schema.String.pipe(Schema.pattern(/^\d{5}(-\d{4})?$/)),
+    }).pipe(Schema.annotations({ description: "Shipping destination" })),
+}).pipe(
+    Schema.annotations({
+        title: "Create Order Input",
+        description: "Input for creating a new order",
+    }),
+)
+```
+
+## Optional Fields
+
+Use `Schema.optional` and `Schema.optionalWith`:
+
+```typescript
+export const UserPreferences = Schema.Struct({
+    // Optional, undefined if not provided
+    theme: Schema.optional(Schema.Literal("light", "dark")),
+
+    // Optional with default value
+    language: Schema.optionalWith(Schema.String, { default: () => "en" }),
+
+    // Optional with null support (for database compatibility)
+    bio: Schema.NullOr(Schema.String),
+
+    // Optional but must be present if set (no undefined)
+    timezone: Schema.optional(Schema.String, { exact: true }),
+})
+```
+
+## Union Types and Discriminated Unions
+
+```typescript
+// Simple union
+export const PaymentMethod = Schema.Union(
+    Schema.Literal("card"),
+    Schema.Literal("bank_transfer"),
+    Schema.Literal("crypto"),
+)
+
+// Discriminated union (tagged)
+export const PaymentDetails = Schema.Union(
+    Schema.Struct({
+        _tag: Schema.Literal("Card"),
+        cardNumber: Schema.String,
+        expiry: Schema.String,
+        cvv: Schema.String,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("BankTransfer"),
+        accountNumber: Schema.String,
+        routingNumber: Schema.String,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("Crypto"),
+        walletAddress: Schema.String,
+        network: Schema.Literal("ethereum", "bitcoin", "solana"),
+    }),
+)
+export type PaymentDetails = Schema.Schema.Type<typeof PaymentDetails>
+
+// Usage with match
+const processPayment = (details: PaymentDetails) => {
+    switch (details._tag) {
+        case "Card":
+            return processCard(details.cardNumber, details.expiry, details.cvv)
+        case "BankTransfer":
+            return processBankTransfer(details.accountNumber, details.routingNumber)
+        case "Crypto":
+            return processCrypto(details.walletAddress, details.network)
+    }
+}
+```
+
+## Enums and Literals
+
+```typescript
+// Use Literal for small, fixed sets
+export const UserRole = Schema.Literal("admin", "member", "viewer")
+export type UserRole = Schema.Schema.Type<typeof UserRole>
+
+// Use Enums for larger sets or when you need runtime values
+export const OrderStatus = Schema.Enums({
+    Pending: "pending",
+    Processing: "processing",
+    Shipped: "shipped",
+    Delivered: "delivered",
+    Cancelled: "cancelled",
+} as const)
+export type OrderStatus = Schema.Schema.Type<typeof OrderStatus>
+```
+
+## Recursive Schemas
+
+```typescript
+interface Category {
+    id: string
+    name: string
+    children: readonly Category[]
+}
+
+export const Category: Schema.Schema<Category> = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    children: Schema.Array(Schema.suspend(() => Category)),
+})
+```
+
+## Decoding and Encoding
+
+```typescript
+// Decode (parse) - use in services
+const parseUser = Schema.decodeUnknown(User)
+const result = yield* parseUser(rawData) // Effect<User, ParseError>
+
+// Decode sync - only in controlled contexts
+const user = Schema.decodeUnknownSync(User)(rawData)
+
+// Encode - for serialization
+const encodeUser = Schema.encode(User)
+const encoded = yield* encodeUser(user) // Effect<UserEncoded, ParseError>
+```

package/dist/skills/frameworks/effect/effect-best-practices/references/service-patterns.md

@@ -0,0 +1,299 @@
+# Service Patterns
+
+## Effect.Service Over Context.Tag
+
+**Always prefer `Effect.Service`** for defining business logic services. This is the modern, recommended approach that provides:
+
+1. **Built-in `Default` layer** - No manual layer creation needed
+2. **Automatic accessors** - Direct method calls via `ServiceName.method()`
+3. **Proper dependency declaration** - Dependencies are explicit and type-checked
+4. **Consistent structure** - All services follow the same pattern
+
+The underlying architecture is the same as the classic `Context.Tag` + `Layer` pattern: a service is a typed capability requirement, and a layer supplies the implementation. Keep that requirement visible in the Effect environment or the service `dependencies` array until a layer provides it.
+
+### Basic Service Definition
+
+```typescript
+import { Effect, Layer } from "effect"
+
+export class UserService extends Effect.Service<UserService>()("UserService", {
+    accessors: true,
+    effect: Effect.gen(function* () {
+        const findById = Effect.fn("UserService.findById")(function* (id: UserId) {
+            // Implementation
+        })
+
+        const findByEmail = Effect.fn("UserService.findByEmail")(function* (email: string) {
+            // Implementation
+        })
+
+        const create = Effect.fn("UserService.create")(function* (input: CreateUserInput) {
+            // Implementation
+        })
+
+        return { findById, findByEmail, create }
+    }),
+}) {}
+```
+
+### Service with Dependencies
+
+**Critical:** Always declare dependencies using the `dependencies` array. This ensures:
+- Dependencies are automatically provided when using `ServiceName.Default`
+- Type errors if dependencies are missing
+- No manual `Layer.provide` at usage sites
+
+```typescript
+export class OrderService extends Effect.Service<OrderService>()("OrderService", {
+    accessors: true,
+    dependencies: [
+        UserService.Default,
+        ProductService.Default,
+        InventoryService.Default,
+    ],
+    effect: Effect.gen(function* () {
+        // Dependencies are automatically available
+        const users = yield* UserService
+        const products = yield* ProductService
+        const inventory = yield* InventoryService
+
+        const create = Effect.fn("OrderService.create")(function* (input: CreateOrderInput) {
+            // Validate user exists
+            const user = yield* users.findById(input.userId)
+
+            // Check product availability
+            const product = yield* products.findById(input.productId)
+            const available = yield* inventory.checkAvailability(input.productId, input.quantity)
+
+            if (!available) {
+                return yield* Effect.fail(new InsufficientInventoryError({
+                    productId: input.productId,
+                    message: "Not enough inventory",
+                }))
+            }
+
+            // Create order...
+        })
+
+        return { create }
+    }),
+}) {}
+```
+
+### Wrong: Leaking Dependencies
+
+```typescript
+// WRONG - Dependencies not declared, must be provided manually
+export class OrderService extends Effect.Service<OrderService>()("OrderService", {
+    accessors: true,
+    effect: Effect.gen(function* () {
+        const users = yield* UserService  // Dependency not in `dependencies` array!
+        // ...
+    }),
+}) {}
+
+// Now every usage site must do this:
+const program = OrderService.create(input).pipe(
+    Effect.provide(UserService.Default),  // Annoying and error-prone
+)
+```
+
+## Effect.fn for Tracing
+
+**Always wrap service methods with `Effect.fn`**. This provides automatic tracing with meaningful span names.
+
+### Naming Convention
+
+Use `ServiceName.methodName` format for span names:
+
+```typescript
+const findById = Effect.fn("UserService.findById")(function* (id: UserId) {
+    yield* Effect.annotateCurrentSpan("userId", id)
+    // Implementation
+})
+
+const processPayment = Effect.fn("PaymentService.processPayment")(
+    function* (orderId: OrderId, amount: number, currency: string) {
+        yield* Effect.annotateCurrentSpan("orderId", orderId)
+        yield* Effect.annotateCurrentSpan("amount", amount)
+        yield* Effect.annotateCurrentSpan("currency", currency)
+        // Implementation
+    }
+)
+```
+
+### Annotating Spans
+
+Add important context to spans, but don't overdo it:
+
+```typescript
+// CORRECT - Important business identifiers
+yield* Effect.annotateCurrentSpan("userId", userId)
+yield* Effect.annotateCurrentSpan("orderId", orderId)
+yield* Effect.annotateCurrentSpan("amount", amount)
+
+// WRONG - Too much detail, noise in traces
+yield* Effect.annotateCurrentSpan("userEmail", user.email)
+yield* Effect.annotateCurrentSpan("userName", user.name)
+yield* Effect.annotateCurrentSpan("userCreatedAt", user.createdAt)
+yield* Effect.annotateCurrentSpan("step", "validating")
+yield* Effect.annotateCurrentSpan("step", "processing")
+yield* Effect.annotateCurrentSpan("step", "completing")
+```
+
+## When Context.Tag is Acceptable
+
+`Context.Tag` is appropriate **only** for infrastructure that's injected at runtime:
+
+### Cloudflare Worker Bindings
+
+```typescript
+import { Context } from "effect"
+
+// These are provided by the runtime, not created by our code
+export class KVNamespace extends Context.Tag("KVNamespace")<
+    KVNamespace,
+    CloudflareKVNamespace
+>() {}
+
+export class R2Bucket extends Context.Tag("R2Bucket")<
+    R2Bucket,
+    CloudflareR2Bucket
+>() {}
+
+// In the worker entry point
+const handler = {
+    fetch(request: Request, env: Env) {
+        return program.pipe(
+            Effect.provideService(KVNamespace, env.MY_KV),
+            Effect.provideService(R2Bucket, env.MY_BUCKET),
+            Effect.runPromise,
+        )
+    }
+}
+```
+
+### Database/Redis Clients (Infrastructure)
+
+```typescript
+// Infrastructure provided at app root - acceptable as Context.Tag
+// But prefer using @effect/sql or similar typed clients
+
+import { PgClient } from "@effect/sql-pg"
+
+// PgClient is already a Context.Tag from the library
+// Just provide it at the app root
+const DatabaseLive = PgClient.layer({
+    host: Config.string("DB_HOST"),
+    port: Config.integer("DB_PORT"),
+    database: Config.string("DB_NAME"),
+    // ...
+})
+```
+
+## Single Responsibility
+
+Each service should have a focused responsibility:
+
+```typescript
+// CORRECT - Focused services
+export class UserService extends Effect.Service<UserService>()("UserService", { /* user operations */ }) {}
+export class AuthService extends Effect.Service<AuthService>()("AuthService", { /* auth operations */ }) {}
+export class NotificationService extends Effect.Service<NotificationService>()("NotificationService", { /* notifications */ }) {}
+
+// WRONG - God service doing everything
+export class AppService extends Effect.Service<AppService>()("AppService", {
+    effect: Effect.gen(function* () {
+        return {
+            createUser,
+            deleteUser,
+            login,
+            logout,
+            sendEmail,
+            sendPush,
+            processPayment,
+            // ... 50 more methods
+        }
+    }),
+}) {}
+```
+
+## Service Interface Patterns
+
+### Return Types
+
+Services should return `Effect` types, never `Promise`:
+
+```typescript
+// CORRECT
+const findById = Effect.fn("UserService.findById")(
+    function* (id: UserId): Effect.Effect<User, UserNotFoundError> {
+        // ...
+    }
+)
+
+// WRONG - Promise in service interface
+const findById = async (id: UserId): Promise<User> => {
+    // ...
+}
+```
+
+### Use Option for Nullable Results
+
+```typescript
+// CORRECT - findById can fail, findByIdOption returns Option
+const findById = Effect.fn("UserService.findById")(
+    function* (id: UserId): Effect.Effect<User, UserNotFoundError> {
+        const maybeUser = yield* repo.findById(id)
+        return yield* Option.match(maybeUser, {
+            onNone: () => Effect.fail(new UserNotFoundError({ userId: id, message: "Not found" })),
+            onSome: Effect.succeed,
+        })
+    }
+)
+
+const findByIdOption = Effect.fn("UserService.findByIdOption")(
+    function* (id: UserId): Effect.Effect<Option<User>> {
+        return yield* repo.findById(id)
+    }
+)
+```
+
+## Testing Services
+
+Create test implementations using the same pattern:
+
+```typescript
+// Test implementation
+export const UserServiceTest = Layer.succeed(
+    UserService,
+    UserService.of({
+        findById: (id) => Effect.succeed(mockUser),
+        create: (input) => Effect.succeed({ ...mockUser, ...input }),
+    })
+)
+
+// Or with Effect.Service for stateful mocks
+export class UserServiceTest extends Effect.Service<UserService>()("UserService", {
+    accessors: true,
+    effect: Effect.gen(function* () {
+        const users = new Map<string, User>()
+
+        const findById = Effect.fn("UserService.findById")(function* (id: UserId) {
+            const user = users.get(id)
+            if (!user) return yield* Effect.fail(new UserNotFoundError({ userId: id, message: "Not found" }))
+            return user
+        })
+
+        const create = Effect.fn("UserService.create")(function* (input: CreateUserInput) {
+            const user = { id: UserId.make(crypto.randomUUID()), ...input }
+            users.set(user.id, user)
+            return user
+        })
+
+        return { findById, create }
+    }),
+}) {}
+```
+
+Do not mock Effect services with `vi.mock`, path-based import rewrites, or mutable module singletons. Tests should provide alternate implementations with `Layer.succeed`, a test `Effect.Service`, or a feature-local `tests/support/layer.ts`.