@dojocho/effect-ts 0.0.1

package/skills/effect-patterns-platform-getting-started/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: effect-patterns-platform-getting-started
+description: Effect-TS patterns for Platform Getting Started. Use when working with platform getting started in Effect-TS applications.
+---
+# Effect-TS Patterns: Platform Getting Started
+This skill provides 2 curated Effect-TS patterns for platform getting started.
+Use this skill when working on tasks related to:
+- platform getting started
+- Best practices in Effect-TS applications
+- Real-world patterns and solutions
+
+---
+
+## 🟢 Beginner Patterns
+
+### Your First Platform Operation
+
+**Rule:** Use @effect/platform for cross-platform system operations with Effect integration.
+
+**Good Example:**
+
+```typescript
+import { Effect } from "effect"
+import { FileSystem } from "@effect/platform"
+import { NodeContext, NodeRuntime } from "@effect/platform-node"
+
+// Read a file - returns Effect<string, PlatformError>
+const readConfig = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  
+  // Read file as UTF-8 string
+  const content = yield* fs.readFileString("./config.json")
+  
+  return JSON.parse(content)
+})
+
+// Write a file
+const writeLog = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  
+  yield* fs.writeFileString(
+    "./app.log",
+    `Started at ${new Date().toISOString()}\n`
+  )
+})
+
+// Combine operations
+const program = Effect.gen(function* () {
+  const config = yield* readConfig
+  yield* Effect.log(`Loaded config: ${config.appName}`)
+  
+  yield* writeLog
+  yield* Effect.log("Log file created")
+})
+
+// Run with Node.js platform
+program.pipe(
+  Effect.provide(NodeContext.layer),
+  NodeRuntime.runMain
+)
+```
+
+**Rationale:**
+
+Effect Platform provides type-safe, cross-platform system operations. Use `@effect/platform-node` for Node.js or `@effect/platform-bun` for Bun.
+
+---
+
+
+Platform wraps system operations in Effect, giving you:
+
+1. **Type safety** - File operations return `Effect<Content, PlatformError>`
+2. **Resource management** - Files are automatically closed
+3. **Cross-platform** - Same code works on Node.js, Bun, browser
+4. **Composability** - Chain file ops with other effects
+
+---
+
+---
+
+### Access Environment Variables
+
+**Rule:** Use Effect to access environment variables with proper error handling.
+
+**Good Example:**
+
+```typescript
+import { Effect, Config, Option } from "effect"
+
+// ============================================
+// BASIC: Read required variable
+// ============================================
+
+const getApiKey = Config.string("API_KEY")
+
+const program1 = Effect.gen(function* () {
+  const apiKey = yield* getApiKey
+  yield* Effect.log(`API Key: ${apiKey.slice(0, 4)}...`)
+})
+
+// ============================================
+// OPTIONAL: With default value
+// ============================================
+
+const getPort = Config.number("PORT").pipe(
+  Config.withDefault(3000)
+)
+
+const program2 = Effect.gen(function* () {
+  const port = yield* getPort
+  yield* Effect.log(`Server will run on port ${port}`)
+})
+
+// ============================================
+// OPTIONAL: Return Option instead of failing
+// ============================================
+
+const getOptionalFeature = Config.string("FEATURE_FLAG").pipe(
+  Config.option
+)
+
+const program3 = Effect.gen(function* () {
+  const feature = yield* getOptionalFeature
+  
+  if (Option.isSome(feature)) {
+    yield* Effect.log(`Feature enabled: ${feature.value}`)
+  } else {
+    yield* Effect.log("Feature flag not set")
+  }
+})
+
+// ============================================
+// COMBINED: Multiple variables as config object
+// ============================================
+
+const AppConfig = Config.all({
+  apiKey: Config.string("API_KEY"),
+  apiUrl: Config.string("API_URL"),
+  port: Config.number("PORT").pipe(Config.withDefault(3000)),
+  debug: Config.boolean("DEBUG").pipe(Config.withDefault(false)),
+})
+
+const program4 = Effect.gen(function* () {
+  const config = yield* AppConfig
+  
+  yield* Effect.log(`API URL: ${config.apiUrl}`)
+  yield* Effect.log(`Port: ${config.port}`)
+  yield* Effect.log(`Debug: ${config.debug}`)
+})
+
+// ============================================
+// RUN: Will fail if required vars missing
+// ============================================
+
+Effect.runPromise(program4).catch((error) => {
+  console.error("Missing required environment variables")
+  console.error(error)
+})
+```
+
+**Rationale:**
+
+Access environment variables using Effect's built-in functions or Platform's environment service for type-safe configuration.
+
+---
+
+
+Environment variables can be missing or malformed. Effect helps you:
+
+1. **Handle missing vars** - Return `Option` or fail with typed error
+2. **Validate values** - Parse and validate with Schema
+3. **Provide defaults** - Fallback values when vars are missing
+4. **Document requirements** - Types show what's needed
+
+---
+
+---
+
+

package/skills/effect-patterns-project-setup--execution/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: effect-patterns-project-setup--execution
+description: Effect-TS patterns for Project Setup  Execution. Use when working with project setup  execution in Effect-TS applications.
+---
+# Effect-TS Patterns: Project Setup  Execution
+This skill provides 4 curated Effect-TS patterns for project setup  execution.
+Use this skill when working on tasks related to:
+- project setup  execution
+- Best practices in Effect-TS applications
+- Real-world patterns and solutions
+
+---
+
+## 🟢 Beginner Patterns
+
+### Execute Synchronous Effects with Effect.runSync
+
+**Rule:** Execute synchronous effects with Effect.runSync.
+
+**Good Example:**
+
+```typescript
+import { Effect } from "effect";
+
+// Simple synchronous program
+const program1 = Effect.gen(function* () {
+  const n = 10;
+  const result = n * 2;
+  yield* Effect.log(`Simple program result: ${result}`);
+  return result;
+});
+
+// Run simple program
+Effect.runSync(program1);
+
+// Program with logging
+const program2 = Effect.gen(function* () {
+  yield* Effect.logInfo("Starting calculation...");
+  const n = yield* Effect.sync(() => 10);
+  yield* Effect.logInfo(`Got number: ${n}`);
+  const result = yield* Effect.sync(() => n * 2);
+  yield* Effect.logInfo(`Result: ${result}`);
+  return result;
+});
+
+// Run with logging
+Effect.runSync(program2);
+
+// Program with error handling
+const program3 = Effect.gen(function* () {
+  yield* Effect.logInfo("Starting division...");
+  const n = yield* Effect.sync(() => 10);
+  const divisor = yield* Effect.sync(() => 0);
+
+  yield* Effect.logInfo(`Attempting to divide ${n} by ${divisor}...`);
+  return yield* Effect.try({
+    try: () => {
+      if (divisor === 0) throw new Error("Cannot divide by zero");
+      return n / divisor;
+    },
+    catch: (error) => {
+      if (error instanceof Error) {
+        return error;
+      }
+      return new Error("Unknown error occurred");
+    },
+  });
+}).pipe(
+  Effect.catchAll((error) => Effect.logInfo(`Error occurred: ${error.message}`))
+);
+
+// Run with error handling
+Effect.runSync(program3);
+```
+
+**Explanation:**  
+Use `runSync` only for Effects that are fully synchronous. If the Effect
+contains async code, use `runPromise` instead.
+
+**Anti-Pattern:**
+
+Do not use `runSync` on an Effect that contains asynchronous operations like
+`Effect.delay` or `Effect.promise`. This will result in a runtime error.
+
+**Rationale:**
+
+To execute an `Effect` that is guaranteed to be synchronous, use
+`Effect.runSync`. This will return the success value directly or throw the
+error.
+
+
+`Effect.runSync` is an optimized runner for Effects that don't involve any
+asynchronous operations. If the Effect contains any async operations,
+`runSync` will throw an error.
+
+---
+
+### Execute Asynchronous Effects with Effect.runPromise
+
+**Rule:** Execute asynchronous effects with Effect.runPromise.
+
+**Good Example:**
+
+```typescript
+import { Effect } from "effect";
+
+const program = Effect.succeed("Hello, World!").pipe(Effect.delay("1 second"));
+
+const promise = Effect.runPromise(program);
+
+const programWithLogging = Effect.gen(function* () {
+  const result = yield* program;
+  yield* Effect.log(result); // Logs "Hello, World!" after 1 second.
+  return result;
+});
+
+Effect.runPromise(programWithLogging);
+```
+
+**Explanation:**  
+`Effect.runPromise` executes your effect and returns a Promise, making it
+easy to integrate with existing JavaScript async workflows.
+
+**Anti-Pattern:**
+
+Never call `runPromise` inside another `Effect` composition. Effects are
+meant to be composed together _before_ being run once at the end.
+
+**Rationale:**
+
+To execute an `Effect` that may be asynchronous and retrieve its result, use
+`Effect.runPromise`. This should only be done at the outermost layer of your
+application.
+
+
+`Effect.runPromise` is the bridge from the Effect world to the Promise-based
+world of Node.js and browsers. If the Effect succeeds, the Promise resolves;
+if it fails, the Promise rejects.
+
+---
+
+### Set Up a New Effect Project
+
+**Rule:** Set up a new Effect project.
+
+**Good Example:**
+
+```typescript
+// 1. Init project (e.g., `npm init -y`)
+// 2. Install deps (e.g., `npm install effect`, `npm install -D typescript tsx`)
+// 3. Create tsconfig.json with `"strict": true`
+// 4. Create src/index.ts
+import { Effect } from "effect";
+
+const program = Effect.log("Hello, World!");
+
+Effect.runSync(program);
+
+// 5. Run the program (e.g., `npx tsx src/index.ts`)
+```
+
+**Explanation:**  
+This setup ensures you have TypeScript and Effect ready to go, with strict
+type-checking for maximum safety and correctness.
+
+**Anti-Pattern:**
+
+Avoid disabling `strict` mode in your `tsconfig.json`. Running with
+`"strict": false` will cause you to lose many of the type-safety guarantees
+that make Effect so powerful.
+
+**Rationale:**
+
+To start a new Effect project, initialize a standard Node.js project, add
+`effect` and `typescript` as dependencies, and create a `tsconfig.json` file
+with strict mode enabled.
+
+
+A proper setup is crucial for leveraging Effect's powerful type-safety
+features. Using TypeScript's `strict` mode is non-negotiable.
+
+---
+
+
+## 🟠 Advanced Patterns
+
+### Create a Reusable Runtime from Layers
+
+**Rule:** Create a reusable runtime from layers.
+
+**Good Example:**
+
+```typescript
+import { Effect, Layer, Runtime } from "effect";
+
+class GreeterService extends Effect.Service<GreeterService>()("Greeter", {
+  sync: () => ({
+    greet: (name: string) => Effect.sync(() => `Hello ${name}`),
+  }),
+}) {}
+
+const runtime = Effect.runSync(
+  Layer.toRuntime(GreeterService.Default).pipe(Effect.scoped)
+);
+
+// In a server, you would reuse `run` for every request.
+Runtime.runPromise(runtime)(Effect.log("Hello"));
+```
+
+**Explanation:**  
+By compiling your layers into a Runtime once, you avoid rebuilding the
+dependency graph for every effect execution.
+
+**Anti-Pattern:**
+
+For a long-running application, avoid providing layers and running an effect
+in a single operation. This forces Effect to rebuild the dependency graph on
+every execution.
+
+**Rationale:**
+
+For applications that need to run multiple effects (e.g., a web server), use
+`Layer.toRuntime(appLayer)` to compile your dependency graph into a single,
+reusable `Runtime` object.
+
+
+Building the dependency graph from layers has a one-time cost. Creating a
+`Runtime` once when your application starts is highly efficient for
+long-running applications.
+
+---
+
+