@effect/sql-sqlite-wasm 4.0.0-beta.98 → 4.0.0-rc.108

package/ai-docs/src/60_child-process/10_working-with-child-processes.ts

@@ -0,0 +1,117 @@
+/**
+ * @title Working with child processes
+ *
+ * This example shows how to collect process output, compose pipelines, and stream long-running command output.
+ */
+import { NodeServices } from "@effect/platform-node"
+import { Console, Context, Effect, Layer, Schema, Stream, String } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+
+export class DevToolsError extends Schema.TaggedError<DevToolsError>()("DevToolsError", {
+  cause: Schema.Defect()
+}) {}
+
+export class DevTools extends Context.Service<DevTools, {
+  readonly nodeVersion: Effect.Effect<string, DevToolsError>
+  readonly recentCommitSubjects: Effect.Effect<ReadonlyArray<string>, DevToolsError>
+  readonly runLintFix: Effect.Effect<void, DevToolsError>
+  changedTypeScriptFiles(baseRef: string): Effect.Effect<ReadonlyArray<string>, DevToolsError>
+}>()("docs/DevTools") {
+  static readonly layer = Layer.effect(
+    DevTools,
+    Effect.gen(function*() {
+      // To run child processes, we need access to a `ChildProcessSpawner`.
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+
+      // Use `spawner.string` when you want to collect the entire output of a
+      // command as a string. This runs `node --version` and collects the
+      // output.
+      const nodeVersion = spawner.string(
+        ChildProcess.make("node", ["--version"])
+      ).pipe(
+        Effect.map(String.trim),
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const changedTypeScriptFiles = Effect.fn("DevTools.changedTypeScriptFiles")(function*(baseRef: string) {
+        yield* Effect.annotateCurrentSpan({ baseRef })
+
+        // `spawner.lines` is a convenience helper for line-oriented command
+        // output.
+        const files = yield* spawner.lines(
+          ChildProcess.make("git", ["diff", "--name-only", `${baseRef}...HEAD`])
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        return files.filter((file) => file.endsWith(".ts"))
+      })
+
+      // Build a pipeline from two command values. This runs:
+      // `git log --pretty=format:%s -n 20 | head -n 5`
+      const recentCommitSubjects = spawner.lines(
+        ChildProcess.make("git", ["log", "--pretty=format:%s", "-n", "20"]).pipe(
+          ChildProcess.pipeTo(ChildProcess.make("head", ["-n", "5"]))
+        )
+      ).pipe(
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const runLintFix = Effect.gen(function*() {
+        // Use `spawn` when you want the process handle and stream output while
+        // the process is still running.
+        const handle = yield* spawner.spawn(
+          ChildProcess.make("pnpm", ["lint-fix"], {
+            env: { FORCE_COLOR: "1" },
+            extendEnv: true
+          })
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        yield* handle.all.pipe(
+          Stream.decodeText(),
+          Stream.splitLines,
+          Stream.runForEach((line) => Console.log(`[lint-fix] ${line}`)),
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        const exitCode = yield* handle.exitCode.pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+          return yield* new DevToolsError({
+            cause: new Error(`pnpm lint-fix failed with exit code ${exitCode}`)
+          })
+        }
+      }).pipe(
+        // `spawner.spawn` adds a `Scope` requirement to manage the lifecycle of
+        // the child process. We can use `Effect.scoped` to provide a `Scope`
+        // and close it when the effect completes.
+        Effect.scoped
+      )
+
+      return DevTools.of({
+        nodeVersion,
+        changedTypeScriptFiles,
+        recentCommitSubjects,
+        runLintFix
+      })
+    })
+  ).pipe(
+    // Provide the `ChildProcessSpawner` dependency from `NodeServices.layer`.
+    Layer.provide(NodeServices.layer)
+  )
+}
+
+export const program = Effect.gen(function*() {
+  const tools = yield* DevTools
+
+  const version = yield* tools.nodeVersion
+  yield* Effect.log(`node=${version}`)
+}).pipe(
+  // `ChildProcess` requires a platform implementation of
+  // `ChildProcessSpawner`. In Node.js, `NodeServices.layer` provides it.
+  Effect.provide(DevTools.layer)
+)

package/ai-docs/src/60_child-process/index.md

@@ -0,0 +1,3 @@
+## Working with child processes
+
+Use the `effect/unstable/process` modules to define child processes and run them with `ChildProcessSpawner`.

package/ai-docs/src/70_cli/10_basics.ts

@@ -0,0 +1,136 @@
+/**
+ * @title Getting started with Effect CLI modules
+ *
+ * Build a command-line app with typed arguments and flags, then wire subcommand
+ * handlers into a single executable command.
+ */
+import { NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Console, Effect } from "effect"
+import { Argument, Command, Flag } from "effect/unstable/cli"
+
+// You can define flags outside of commands and reuse them across multiple
+// commands.
+const workspace = Flag.string("workspace").pipe(
+  Flag.withAlias("w"),
+  Flag.withDescription("Workspace to operate on"),
+  Flag.withDefault("personal")
+)
+
+// Start with a root command and explicitly share the parent flags that should
+// be available to all subcommands.
+const tasks = Command.make("tasks").pipe(
+  Command.withSharedFlags({
+    workspace,
+    verbose: Flag.boolean("verbose").pipe(
+      Flag.withAlias("v"),
+      Flag.withDescription("Print diagnostic output")
+    )
+  }),
+  Command.withDescription("Track and manage tasks")
+)
+
+const create = Command.make(
+  "create",
+  {
+    title: Argument.string("title").pipe(
+      Argument.withDescription("Task title")
+    ),
+    priority: Flag.choice("priority", ["low", "normal", "high"]).pipe(
+      Flag.withDescription("Priority for the new task"),
+      Flag.withDefault("normal")
+    )
+  },
+  Effect.fn(function*({ title, priority }) {
+    // Subcommands can read parent command input by yielding the parent command.
+    const root = yield* tasks
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=create`)
+    }
+
+    yield* Console.log(`Created "${title}" in ${root.workspace} with ${priority} priority`)
+  })
+).pipe(
+  Command.withDescription("Create a task"),
+  Command.withExamples([
+    {
+      command: "tasks create \"Ship 4.0\" --priority high",
+      description: "Create a high-priority task"
+    }
+  ])
+)
+
+const list = Command.make(
+  "list",
+  {
+    status: Flag.choice("status", ["open", "done", "all"]).pipe(
+      Flag.withDescription("Filter tasks by status"),
+      Flag.withDefault("open")
+    ),
+    json: Flag.boolean("json").pipe(
+      Flag.withDescription("Print machine-readable output")
+    )
+  },
+  Effect.fn(function*({ status, json }) {
+    const root = yield* tasks
+    const items = [
+      { title: "Ship 4.0", status: "open" },
+      { title: "Update onboarding guide", status: "done" }
+    ] as const
+    const filtered = status === "all"
+      ? items
+      : items.filter((item) => item.status === status)
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=list`)
+    }
+
+    if (json) {
+      yield* Console.log(JSON.stringify(
+        {
+          workspace: root.workspace,
+          status,
+          items: filtered
+        },
+        null,
+        2
+      ))
+      return
+    }
+
+    yield* Console.log(`Listing ${status} tasks in ${root.workspace}`)
+    if (filtered.length === 0) {
+      yield* Console.log("- No tasks found")
+      return
+    }
+
+    for (const item of filtered) {
+      yield* Console.log(`- ${item.title}`)
+    }
+  })
+).pipe(
+  Command.withDescription("List tasks"),
+  Command.withAlias("ls"),
+  Command.withExamples([
+    {
+      command: "tasks --workspace team-a list --status open",
+      description: "List open tasks in a specific workspace"
+    },
+    {
+      command: "tasks --workspace team-b ls --status open",
+      description: "List open tasks in another workspace"
+    }
+  ])
+)
+
+// Finally, compose the subcommands into a single command and then run it.
+tasks.pipe(
+  Command.withSubcommands([create, list]),
+  Command.run({
+    version: "1.0.0"
+  }),
+  // Provide the services for the platform you are targeting. In this case,
+  // Node.js
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain
+)

package/ai-docs/src/70_cli/index.md

@@ -0,0 +1,5 @@
+## Building CLI applications
+
+Use the "effect/unstable/cli" modules to build CLI applications. These modules
+provide utilities for parsing command-line arguments, handling user input, and
+managing the flow of a CLI application.

package/ai-docs/src/71_ai/10_language-model.ts

@@ -0,0 +1,156 @@
+/**
+ * @title Using LanguageModel for text, objects, and streams
+ *
+ * Configure a provider once, then use `LanguageModel` for plain text
+ * generation, schema-validated object generation, and streaming responses.
+ */
+import { AnthropicClient, AnthropicLanguageModel } from "@effect/ai-anthropic"
+import { OpenAiClient, OpenAiLanguageModel } from "@effect/ai-openai"
+import { Config, Context, Effect, ExecutionPlan, Layer, Schema, Stream } from "effect"
+import { AiError, LanguageModel, Model, type Response } from "effect/unstable/ai"
+import { FetchHttpClient } from "effect/unstable/http"
+import { LaunchPlan } from "./fixtures/domain/LaunchPlan.ts"
+
+// You can use Config to create ai clients
+const AnthropicClientLayer = AnthropicClient.layerConfig({
+  apiKey: Config.redacted("ANTHROPIC_API_KEY")
+}).pipe(
+  // Providers typically require an HttpClient, but you can choose which one to
+  // use.
+  Layer.provide(FetchHttpClient.layer)
+)
+
+const OpenAiClientLayer = OpenAiClient.layerConfig({
+  apiKey: Config.redacted("OPENAI_API_KEY")
+}).pipe(
+  Layer.provide(FetchHttpClient.layer)
+)
+
+export class AiWriterError extends Schema.TaggedError<AiWriterError>()("AiWriterError", {
+  // AiErrorReason is a Schema, so we can include it directly in our custom
+  // error schema.
+  reason: AiError.AiErrorReason
+}) {
+  static fromAiError(error: AiError.AiError) {
+    return new AiWriterError({
+      reason: error.reason
+    })
+  }
+}
+
+// You can use `ExecutionPlan` to define a strategy for trying multiple
+// providers with different configurations. In this example, we try a cheaper
+// OpenAI model first, then fall back to a more expensive Anthropic model if the
+// first one fails.
+const DraftPlan = ExecutionPlan.make(
+  {
+    provide: OpenAiLanguageModel.model("gpt-5.2"),
+    // Attempt to use the openai model up to 3 times before falling back to the
+    // anthropic model.
+    attempts: 3
+  },
+  {
+    provide: AnthropicLanguageModel.model("claude-opus-4-6"),
+    attempts: 2
+  }
+)
+
+export class AiWriter extends Context.Service<AiWriter, {
+  draftAnnouncement(product: string): Effect.Effect<{
+    readonly provider: string
+    readonly text: string
+  }, AiWriterError>
+  extractLaunchPlan(notes: string): Effect.Effect<LaunchPlan, AiWriterError>
+  streamReleaseHighlights(version: string): Stream.Stream<string, AiWriterError>
+}>()("docs/AiWriter") {
+  static readonly layer = Layer.effect(
+    AiWriter,
+    Effect.gen(function*() {
+      // Calling `captureRequirements` on an `ExecutionPlan` will move the
+      // requirements of the plan (in this case the ai clients) into the Layer
+      // requirements.
+      const draftsModel = yield* DraftPlan.captureRequirements
+
+      // Use a different model for the launch plan extraction
+      const launchPlanModel = yield* OpenAiLanguageModel.model("gpt-4.1").captureRequirements
+
+      const draftAnnouncement = Effect.fn("AiWriter.draftAnnouncement")(
+        function*(product: string) {
+          const model = yield* LanguageModel.LanguageModel
+          const provider = yield* Model.ProviderName
+          const response = yield* model.generateText({
+            prompt: `Write a short launch announcement for ${product}. ` +
+              "Keep it concise and include one concrete user benefit."
+          })
+
+          // `LanguageModel.generateText` exposes convenience fields so you can
+          // inspect usage and finish reason without parsing content parts.
+          yield* Effect.logInfo(
+            `${provider} finished with ${response.finishReason}. outputTokens=${response.usage.outputTokens.total}`
+          )
+
+          return {
+            provider,
+            text: response.text
+          }
+        },
+        // To apply an `ExecutionPlan`, we use `Effect.withExecutionPlan`
+        Effect.withExecutionPlan(draftsModel),
+        // Map AiError into our custom error type
+        Effect.mapError((error) => AiWriterError.fromAiError(error))
+      )
+
+      const extractLaunchPlan = Effect.fn("AiWriter.extractLaunchPlan")(
+        function*(notes: string) {
+          const model = yield* LanguageModel.LanguageModel
+          const response = yield* model.generateObject({
+            objectName: "launch_plan",
+            prompt:
+              "Convert these notes into a launch plan object with audience, channels, launchDate, summary, and keyRisks:\n" +
+              notes,
+            // The generated object is validated and decoded through this schema.
+            schema: LaunchPlan
+          })
+
+          return response.value
+        },
+        // The .model(...) apis return a Layer that can be used with
+        // Effect.provide
+        Effect.provide(launchPlanModel),
+        // Map AiError into our custom error type
+        Effect.mapError((error) => AiWriterError.fromAiError(error))
+      )
+
+      const streamReleaseHighlights = (version: string) =>
+        LanguageModel.streamText({
+          prompt: `Write release highlights for version ${version} as a short bulleted list.`
+        }).pipe(
+          Stream.filter((part): part is Response.TextDeltaPart => part.type === "text-delta"),
+          Stream.map((part) => part.delta),
+          Stream.provide(launchPlanModel),
+          // Map AiError into our custom error type
+          Stream.mapError((error) => AiWriterError.fromAiError(error))
+        )
+
+      return AiWriter.of({
+        draftAnnouncement,
+        extractLaunchPlan,
+        streamReleaseHighlights
+      })
+    })
+  ).pipe(
+    // This Layer has requirements for both the OpenAI and Anthropic clients,
+    // since the ExecutionPlan includes models from both providers.
+    Layer.provide([OpenAiClientLayer, AnthropicClientLayer])
+  )
+}
+
+// We can now use `AiWriter` like any other Effect service.
+export const program: Effect.Effect<
+  void,
+  AiWriterError,
+  AiWriter
+> = Effect.gen(function*() {
+  const writer = yield* AiWriter
+  yield* writer.draftAnnouncement("Effect Cloud")
+})

package/ai-docs/src/71_ai/20_tools.ts

@@ -0,0 +1,226 @@
+/**
+ * @title Defining and using AI tools
+ *
+ * Define tools with schemas, group them into toolkits, implement handlers,
+ * and pass them to `LanguageModel.generateText`.
+ */
+import { OpenAiClient, OpenAiLanguageModel, OpenAiTool } from "@effect/ai-openai"
+import { Config, Context, Effect, Layer, Schema } from "effect"
+import { AiError, LanguageModel, Tool, Toolkit } from "effect/unstable/ai"
+import { FetchHttpClient } from "effect/unstable/http"
+
+// ---------------------------------------------------------------------------
+// 1. Defining tools
+// ---------------------------------------------------------------------------
+
+const ProductId = Schema.String.pipe(Schema.brand("ProductId")).annotate({
+  description: "A unique identifier for a product, e.g. 'p-123'"
+})
+
+class Product extends Schema.Class<Product>("acme/domain/Product")({
+  id: ProductId,
+  name: Schema.String,
+  price: Schema.Finite
+}) {}
+
+// Each tool has a name, an optional description, a parameters schema that the
+// model fills in, and a success schema for the handler result. The description
+// is shown to the model to help it decide when to call the tool.
+const SearchProducts = Tool.make("SearchProducts", {
+  description: "Search the product catalog by keyword",
+  parameters: Schema.Struct({
+    query: Schema.String.annotate({
+      // Add a description to individual parameters for even better model
+      // guidance.
+      description: "The search query, e.g. 'wireless headphones'"
+    }),
+    maxResults: Schema.Natural.pipe(Schema.withDecodingDefault(Effect.succeed(10))).annotate({
+      description: "The maximum number of results to return"
+    })
+  }),
+  success: Schema.Array(Product),
+  // The strategy used for handling errors returned from tool call handler
+  // execution.
+  //
+  // If set to `"error"` (the default), errors that occur during tool call handler
+  // execution will be returned in the error channel of the calling effect.
+  //
+  // If set to `"return"`, errors that occur during tool call handler execution
+  // will be captured and returned as part of the tool call result.
+  failureMode: "error"
+})
+
+const GetInventory = Tool.make("GetInventory", {
+  description: "Check current stock level for a product",
+  parameters: Schema.Struct({
+    productId: ProductId
+  }),
+  success: Schema.Struct({
+    productId: ProductId,
+    available: Schema.Natural
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Grouping tools into a Toolkit
+// ---------------------------------------------------------------------------
+
+// `Toolkit.make` accepts any number of tools and produces a typed toolkit that
+// knows the names and schemas of every tool it contains.
+const ProductToolkit = Toolkit.make(SearchProducts, GetInventory)
+
+// ---------------------------------------------------------------------------
+// 3. Implementing handlers via toLayer
+// ---------------------------------------------------------------------------
+
+// `toLayer` returns a `Layer` that satisfies the handler requirements for every
+// tool in the toolkit. Each handler receives the decoded parameters and returns
+// an Effect producing the success type.
+const ProductToolkitLayer = ProductToolkit.toLayer(Effect.gen(function*() {
+  yield* Effect.log("Initializing ProductToolkitLive")
+  // Here you could access other services or resources needed to implement the
+  // handlers, e.g. a database client or external API client.
+  //
+  // const client = yield* SomeDatabaseClient
+  return ProductToolkit.of({
+    SearchProducts: Effect.fn("ProductToolkit.SearchProducts")(function*({ query, maxResults }) {
+      return [
+        new Product({ id: ProductId.make("p-1"), name: `${query} widget`, price: 19.99 }),
+        new Product({ id: ProductId.make("p-2"), name: `${query} gadget`, price: 29.99 })
+      ].slice(0, maxResults)
+    }),
+    GetInventory: Effect.fn("ProductToolkit.GetInventory")(function*({ productId }) {
+      return { productId, available: 42 }
+    })
+  })
+}))
+
+// ---------------------------------------------------------------------------
+// 4. Using tools with LanguageModel
+// ---------------------------------------------------------------------------
+
+// Provider setup (same pattern as the language-model example).
+const OpenAiClientLayer = OpenAiClient.layerConfig({
+  apiKey: Config.redacted("OPENAI_API_KEY")
+}).pipe(Layer.provide(FetchHttpClient.layer))
+
+export class ProductAssistantError extends Schema.TaggedError<ProductAssistantError>()(
+  "ProductAssistantError",
+  { reason: AiError.AiErrorReason }
+) {}
+
+// Wrap tool-enabled generation in a service
+export class ProductAssistant extends Context.Service<ProductAssistant, {
+  answer(question: string): Effect.Effect<{
+    readonly text: string
+    readonly toolCallCount: number
+  }, ProductAssistantError>
+}>()("docs/ProductAssistant") {
+  static readonly layer = Layer.effect(
+    ProductAssistant,
+    Effect.gen(function*() {
+      // Access the toolkit's handlers by yielding the toolkit definition.
+      const toolkit = yield* ProductToolkit
+
+      // Choose a model to use
+      const model = yield* OpenAiLanguageModel.model("gpt-5.2").captureRequirements
+
+      const answer = Effect.fn("ProductAssistant.answer")(
+        function*(question: string) {
+          // Pass the toolkit to `generateText`. The model can call any tool in
+          // the toolkit; the framework resolves parameters, invokes handlers,
+          // and feeds results back automatically.
+          const response = yield* LanguageModel.generateText({
+            prompt: question,
+            toolkit,
+            // You can set `toolChoice` to "required" to force the model to call
+            // a tool before responding with text.
+            //
+            // By default it is set to "auto"
+            toolChoice: "required"
+          })
+
+          // -------------------------------------------------------------------
+          // 5. Inspecting tool calls and results
+          // -------------------------------------------------------------------
+
+          // `response.toolCalls` lists every tool the model invoked, each with
+          // the tool name, a unique id, and the decoded parameters.
+          for (const call of response.toolCalls) {
+            yield* Effect.log(`Tool call: ${call.name} id=${call.id}`)
+          }
+
+          // `response.toolResults` lists the resolved results, each with the
+          // tool name, id, decoded result, and an `isFailure` flag.
+          for (const result of response.toolResults) {
+            yield* Effect.log(
+              `Tool result: ${result.name} id=${result.id} isFailure=${result.isFailure}`
+            )
+          }
+
+          return {
+            text: response.text,
+            toolCallCount: response.toolCalls.length
+          }
+        },
+        // Provide the chosen model to use
+        Effect.provide(model),
+        (_) => _,
+        // Map AI errors into our domain error type
+        Effect.catchTag(
+          "AiError",
+          (error) =>
+            Effect.fail(
+              new ProductAssistantError({
+                reason: error.reason
+              })
+            ),
+          // For unexpected errors, die with the original error
+          (e) => Effect.die(e)
+        )
+      )
+
+      return ProductAssistant.of({ answer })
+    })
+  ).pipe(
+    // The toolkit handler layer must be provided so the framework can invoke
+    // the tool handlers when the model makes tool calls.
+    Layer.provide(ProductToolkitLayer),
+    // Also provide the openai client required by OpenAiLanguageModel.model
+    Layer.provide(OpenAiClientLayer)
+  )
+}
+
+// ---------------------------------------------------------------------------
+// 6. Provider-defined tools
+// ---------------------------------------------------------------------------
+
+// Some providers offer built-in tools (web search, code interpreter, etc.)
+// that run server-side. Use `Tool.providerDefined` or the pre-built
+// definitions from provider packages.
+
+// OpenAI's web search tool is pre-defined in `@effect/ai-openai`. Calling it
+// produces a tool instance that can be merged into any toolkit.
+const webSearch = OpenAiTool.WebSearch({
+  search_context_size: "medium"
+})
+
+// Combine user-defined and provider-defined tools in a single toolkit.
+const AssistantToolkit = Toolkit.make(SearchProducts, GetInventory, webSearch)
+
+// Only user-defined tools that require handlers appear in `toLayer`. The
+// provider-defined `WebSearch` is executed server-side by the provider.
+export const AssistantToolkitLayer = AssistantToolkit.toLayer(Effect.gen(function*() {
+  yield* Effect.log("Initializing AssistantToolkitLive")
+  return AssistantToolkit.of({
+    SearchProducts: Effect.fn("AssistantToolkit.SearchProducts")(function*({ query, maxResults }) {
+      return [
+        new Product({ id: ProductId.make("p-1"), name: `${query} widget`, price: 19.99 }),
+        new Product({ id: ProductId.make("p-2"), name: `${query} gadget`, price: 29.99 })
+      ].slice(0, maxResults)
+    }),
+    GetInventory: Effect.fn("AssistantToolkit.GetInventory")(function*({ productId }) {
+      return { productId, available: 42 }
+    })
+  })
+}))