@effect/platform-cloudflare 0.0.0 → 4.1.3

package/ai-docs/src/01_effect/01_basics/10_creating-effects.ts

@@ -0,0 +1,74 @@
+/**
+ * @title Creating effects from common sources
+ *
+ * Learn how to create effects from various sources, including plain values,
+ * synchronous code, Promise APIs, optional values, and callback-based APIs.
+ */
+import { Effect, Schema } from "effect"
+
+class InvalidPayload extends Schema.TaggedError<InvalidPayload>()("InvalidPayload", {
+  input: Schema.String,
+  cause: Schema.Defect()
+}) {}
+
+class UserLookupError extends Schema.TaggedError<UserLookupError>()("UserLookupError", {
+  userId: Schema.Int,
+  cause: Schema.Defect()
+}) {}
+
+class MissingWorkspaceId extends Schema.TaggedError<MissingWorkspaceId>()("MissingWorkspaceId", {}) {}
+
+// Some request fields are optional and may be absent.
+const requestHeaders = new Map<string, string>([
+  ["x-request-id", "req_1"]
+])
+
+// `Effect.succeed` wraps values you already have in memory.
+export const fromValue = Effect.succeed({ env: "prod", retries: 3 })
+
+// `Effect.sync` wraps synchronous side effects that should not throw.
+export const fromSyncSideEffect = Effect.sync(() => Date.now())
+
+// `Effect.try` wraps synchronous code that may throw.
+export const parsePayload = Effect.fn("parsePayload")((input: string) =>
+  Effect.try({
+    try: () => JSON.parse(input) as { readonly userId: number },
+    catch: (cause) => new InvalidPayload({ input, cause })
+  })
+)
+
+const users = new Map<number, { readonly id: number; readonly name: string }>([
+  [1, { id: 1, name: "Ada" }],
+  [2, { id: 2, name: "Lin" }]
+])
+
+// `Effect.tryPromise` wraps Promise-based APIs that can reject or throw.
+export const fetchUser = Effect.fn("fetchUser")((userId: number) =>
+  Effect.tryPromise({
+    async try() {
+      const user = users.get(userId)
+      if (!user) {
+        throw new Error(`Missing user ${userId}`)
+      }
+      return user
+    },
+    catch: (cause) => new UserLookupError({ userId, cause })
+  })
+)
+
+// `Effect.fromNullishOr` turns nullable values into a typed effect.
+export const fromNullishHeader = Effect.fromNullishOr(requestHeaders.get("x-workspace-id")).pipe(
+  Effect.mapError(() => new MissingWorkspaceId())
+)
+
+// `Effect.callback` wraps callback-style asynchronous APIs.
+export const fromCallback = Effect.callback<number>((resume) => {
+  const timeoutId = setTimeout(() => {
+    resume(Effect.succeed(200))
+  }, 10)
+
+  // Return a finalizer so interruption can cancel the callback source.
+  return Effect.sync(() => {
+    clearTimeout(timeoutId)
+  })
+})

package/ai-docs/src/01_effect/01_basics/index.md

@@ -0,0 +1,7 @@
+## Writing `Effect` code
+
+Prefer `Effect.gen` for inline Effect code. For reusable functions, prefer
+`Effect.fn("name")` when tracing is useful and `Effect.fnUntraced` when it is not,
+particularly in library implementations and hot paths. Avoid functions that only
+wrap and return `Effect.gen`. Attach additional behaviour with combinators; this
+style is more readable and easier to maintain than using combinators alone.

package/ai-docs/src/01_effect/02_schema/10_schema-basics.ts

@@ -0,0 +1,43 @@
+/**
+ * @title Schema basics
+ *
+ * Define `Schema.Class`s, decode unknown input into typed values, and
+ * encode typed values back into their external representation.
+ */
+import { Effect, Schema } from "effect"
+
+// Schema.Class defines both a runtime validator and a TypeScript class.
+// This is useful for domain models that should only be constructed from valid
+// data.
+//
+// The static `Type` and `Encoded` members are available when you need
+// the decoded or encoded TypeScript representation.
+export class User extends Schema.Class<User>("path/to/module/User")({
+  id: Schema.Int,
+  name: Schema.NonEmptyString,
+  email: Schema.String,
+  role: Schema.Literals(["admin", "member"])
+}) {}
+
+// `UserType` will be the type `User`, as schema classes use the class type as
+// the validated type.
+export type UserType = typeof User["Type"]
+
+// Access the encoded type with `typeof YourSchema["Encoded"]`.
+export type UserEncoded = typeof User["Encoded"]
+
+// Reuse parsers at the edges of your application instead of rebuilding them for
+// every request. Use the Effect-returning APIs when you are already inside
+// Effect code so validation errors remain typed in the error channel.
+export const decodeUser = Schema.decodeUnknownEffect(User)
+export const encodeUser = Schema.encodeEffect(User)
+
+export class InvalidUserPayload extends Schema.TaggedError<InvalidUserPayload>()("InvalidUserPayload", {
+  message: Schema.String
+}) {}
+
+export const parseUserPayload = Effect.fn("parseUserPayload")((input: unknown) =>
+  decodeUser(input).pipe(
+    Effect.mapError((error) => new InvalidUserPayload({ message: error.message }))
+  )
+)

package/ai-docs/src/01_effect/02_schema/index.md

@@ -0,0 +1,7 @@
+## Defining schemas and domain models
+
+All validation and domain modeling in Effect is done with `Schema`.
+
+**AVOID using predicates or manual parsing**, instead use `Schema` to parse untrusted data and validate it.
+
+For a comprehensive guide, see [SCHEMA.md](https://github.com/Effect-TS/effect/blob/main/packages/effect/SCHEMA.md). Make sure to read the guide in chunks, as it is a large document.

package/ai-docs/src/01_effect/03_services/01_service.ts

@@ -0,0 +1,45 @@
+/**
+ * @title Context.Service
+ *
+ * The default way to define a service is to extend `Context.Service`,
+ * passing in the service interface as a type parameter.
+ */
+
+// file: src/db/Database.ts
+import { Context, Effect, Layer, Schema } from "effect"
+
+// Pass in the service class name as the first type parameter, and the service
+// interface as the second type parameter.
+export class Database extends Context.Service<Database, {
+  query(sql: string): Effect.Effect<Array<unknown>, DatabaseError>
+}>()(
+  // The string identifier for the service, which should include the package
+  // name and the subdirectory path to the service file.
+  "myapp/db/Database"
+) {
+  // Attach a static layer to the service, which will be used to provide an
+  // implementation of the service.
+  static readonly layer = Layer.effect(
+    Database,
+    Effect.gen(function*() {
+      // Define the service methods using Effect.fn
+      const query = Effect.fn("Database.query")(function*(sql: string) {
+        yield* Effect.log("Executing SQL query:", sql)
+        return [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+      })
+
+      // Return an instance of the service using Database.of, passing in an
+      // object that implements the service interface.
+      return Database.of({
+        query
+      })
+    })
+  )
+}
+
+export class DatabaseError extends Schema.TaggedError<DatabaseError>()("DatabaseError", {
+  cause: Schema.Defect()
+}) {}
+
+// If you ever need to access the service type, use `Database["Service"]`
+export type DatabaseService = Database["Service"]

package/ai-docs/src/01_effect/03_services/10_reference.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Context.Reference
+ *
+ * For defining configuration values, feature flags, or any other service that has a default value.
+ */
+import { Context } from "effect"
+
+export const FeatureFlag = Context.Reference<boolean>("myapp/FeatureFlag", {
+  defaultValue: () => false
+})

package/ai-docs/src/01_effect/03_services/20_layer-composition.ts

@@ -0,0 +1,70 @@
+/**
+ * @title Composing services with the Layer module
+ *
+ * Build focused service layers, then compose them with `Layer.provide` and
+ * `Layer.provideMerge` based on what services you want to expose.
+ */
+
+import { PgClient } from "@effect/sql-pg"
+import { Array, Config, Context, Effect, Layer, type Option, Schema } from "effect"
+import { SqlClient, SqlError } from "effect/sql"
+
+// Define a layer for the SqlClient service
+export const SqlClientLayer: Layer.Layer<
+  PgClient.PgClient | SqlClient.SqlClient,
+  Config.ConfigError | SqlError.SqlError
+> = PgClient.layerConfig({
+  url: Config.Redacted("DATABASE_URL")
+})
+
+export class UserRespositoryError extends Schema.TaggedError<UserRespositoryError>()("UserRespositoryError", {
+  reason: SqlError.SqlError
+}) {}
+
+export class UserRepository extends Context.Service<UserRepository, {
+  findById(id: string): Effect.Effect<
+    Option.Option<{ readonly id: string; readonly name: string }>,
+    UserRespositoryError
+  >
+}>()("myapp/UserRepository") {
+  // Implement the layer for the UserRepository service, which depends on the
+  // SqlClient service
+  static readonly layerNoDeps: Layer.Layer<
+    UserRepository,
+    never,
+    SqlClient.SqlClient
+  > = Layer.effect(
+    UserRepository,
+    Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+
+      const findById = Effect.fn("UserRepository.findById")(function*(id: string) {
+        const results = yield* sql<{
+          readonly id: string
+          readonly name: string
+        }>`SELECT * FROM users WHERE id = '${id}'`
+        return Array.head(results)
+      }, Effect.mapError((reason) => new UserRespositoryError({ reason })))
+
+      return UserRepository.of({ findById })
+    })
+  )
+
+  // Use Layer.provide to compose the UserRepository layer with the SqlClient
+  // layer, exposing only the UserRepository service
+  static readonly layer: Layer.Layer<
+    UserRepository,
+    Config.ConfigError | SqlError.SqlError
+  > = this.layerNoDeps.pipe(
+    Layer.provide(SqlClientLayer)
+  )
+
+  // Use Layer.provideMerge to compose the UserRepository layer with the SqlClient
+  // layer, exposing both the UserRepository and SqlClient services
+  static readonly layerWithSqlClient: Layer.Layer<
+    UserRepository | SqlClient.SqlClient,
+    Config.ConfigError | SqlError.SqlError
+  > = this.layerNoDeps.pipe(
+    Layer.provideMerge(SqlClientLayer)
+  )
+}

package/ai-docs/src/01_effect/03_services/20_layer-unwrap.ts

@@ -0,0 +1,66 @@
+/**
+ * @title Creating Layers from configuration and/or Effects
+ *
+ * Build a layer dynamically from an Effect / Config with `Layer.unwrap`.
+ */
+import { Config, Context, Effect, Layer, Schema } from "effect"
+
+export class MessageStoreError extends Schema.TaggedError<MessageStoreError>()("MessageStoreError", {
+  cause: Schema.Defect()
+}) {}
+
+export class MessageStore extends Context.Service<MessageStore, {
+  append(message: string): Effect.Effect<void>
+  readonly all: Effect.Effect<ReadonlyArray<string>>
+}>()("myapp/MessageStore") {
+  static readonly layerInMemory = Layer.effect(
+    MessageStore,
+    Effect.sync(() => {
+      const messages: Array<string> = []
+
+      return MessageStore.of({
+        append: (message) =>
+          Effect.sync(() => {
+            messages.push(message)
+          }),
+        all: Effect.sync(() => [...messages])
+      })
+    })
+  )
+
+  static readonly layerRemote = (url: URL) =>
+    Layer.effect(
+      MessageStore,
+      Effect.try({
+        try: () => {
+          // In a real app this is where you would open a network connection.
+          const messages: Array<string> = []
+
+          return MessageStore.of({
+            append: (message) =>
+              Effect.sync(() => {
+                messages.push(`[${url.host}] ${message}`)
+              }),
+            all: Effect.sync(() => [...messages])
+          })
+        },
+        catch: (cause) => new MessageStoreError({ cause })
+      })
+    )
+
+  static readonly layer = Layer.unwrap(
+    Effect.gen(function*() {
+      // Read config inside an Effect, then choose which concrete layer to use.
+      const useInMemory = yield* Config.Boolean("MESSAGE_STORE_IN_MEMORY").pipe(
+        Config.withDefault(false)
+      )
+
+      if (useInMemory) {
+        return MessageStore.layerInMemory
+      }
+
+      const remoteUrl = yield* Config.URL("MESSAGE_STORE_URL")
+      return MessageStore.layerRemote(remoteUrl)
+    })
+  )
+}

package/ai-docs/src/01_effect/03_services/index.md

@@ -0,0 +1,5 @@
+## Writing Effect services
+
+Effect services are the most common way to structure Effect code. Prefer using
+services to encapsulate behaviour over other approaches, as it ensures that your
+code is modular, testable, and maintainable.

package/ai-docs/src/01_effect/04_errors/01_error-handling.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Error handling basics
+ *
+ * Defining custom errors and handling them with Effect.catch and Effect.catchTag.
+ */
+import { Effect, Schema } from "effect"
+
+// Define custom errors using Schema.TaggedError
+export class ParseError extends Schema.TaggedError<ParseError>()("ParseError", {
+  input: Schema.String,
+  message: Schema.String
+}) {}
+
+export class ReservedPortError extends Schema.TaggedError<ReservedPortError>()("ReservedPortError", {
+  port: Schema.Int
+}) {}
+
+declare const loadPort: (input: string) => Effect.Effect<number, ParseError | ReservedPortError>
+
+export const recovered = loadPort("80").pipe(
+  // Catch multiple errors with Effect.catchTag, and return a default port number.
+  Effect.catchTag(["ParseError", "ReservedPortError"], (_) => Effect.succeed(3000))
+)
+
+export const withFinalFallback = loadPort("invalid").pipe(
+  // Catch a specific error with Effect.catchTag
+  Effect.catchTag("ReservedPortError", (_) => Effect.succeed(3000)),
+  // Catch all errors with Effect.catch
+  Effect.catch((_) => Effect.succeed(3000))
+)

package/ai-docs/src/01_effect/04_errors/10_catch-tags.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Catch multiple errors with Effect.catchTags
+ *
+ * Use `Effect.catchTags` to handle several tagged errors in one place.
+ */
+
+import { Effect, Schema } from "effect"
+
+export class ValidationError extends Schema.TaggedError<ValidationError>()("ValidationError", {
+  message: Schema.String
+}) {}
+
+export class NetworkError extends Schema.TaggedError<NetworkError>()("NetworkError", {
+  statusCode: Schema.Int
+}) {}
+
+declare const fetchUser: (id: string) => Effect.Effect<string, ValidationError | NetworkError>
+
+export const userOrFallback = fetchUser("123").pipe(
+  Effect.catchTags({
+    ValidationError: (error) => Effect.succeed(`Validation failed: ${error.message}`),
+    NetworkError: (error) => Effect.succeed(`Network request failed with status ${error.statusCode}`)
+  })
+)

package/ai-docs/src/01_effect/04_errors/20_reason-errors.ts

@@ -0,0 +1,64 @@
+/**
+ * @title Creating and handling errors with reasons
+ *
+ * Define a tagged error with a tagged `reason` field, then recover with
+ * `Effect.catchReason`, `Effect.catchReasons`, or by unwrapping the reason into
+ * the error channel with `Effect.unwrapReason`.
+ */
+
+import { Effect, Schema } from "effect"
+
+export class RateLimitError extends Schema.TaggedError<RateLimitError>()("RateLimitError", {
+  retryAfter: Schema.Finite
+}) {}
+
+export class QuotaExceededError extends Schema.TaggedError<QuotaExceededError>()("QuotaExceededError", {
+  limit: Schema.Int
+}) {}
+
+export class SafetyBlockedError extends Schema.TaggedError<SafetyBlockedError>()("SafetyBlockedError", {
+  category: Schema.String
+}) {}
+
+export class AiError extends Schema.TaggedError<AiError>()("AiError", {
+  reason: Schema.Union([RateLimitError, QuotaExceededError, SafetyBlockedError])
+}) {}
+
+declare const callModel: Effect.Effect<string, AiError>
+
+export const handleOneReason = callModel.pipe(
+  // Use `Effect.catchReason` to handle a specific reason type
+  Effect.catchReason(
+    "AiError", // The parent error _tag to catch
+    "RateLimitError", // The reason _tag to catch
+    // The handler for the caught reason
+    (reason) => Effect.succeed(`Retry after ${reason.retryAfter} seconds`),
+    // Optionally handle all the other reasons with a catch-all handler
+    (reason) => Effect.succeed(`Model call failed for reason: ${reason._tag}`)
+  )
+)
+
+export const handleMultipleReasons = callModel.pipe(
+  // Use `Effect.catchReasons` to handle multiple reason types for a given error
+  // in one go
+  Effect.catchReasons(
+    "AiError",
+    {
+      RateLimitError: (reason) => Effect.succeed(`Retry after ${reason.retryAfter} seconds`),
+      QuotaExceededError: (reason) => Effect.succeed(`Quota exceeded at ${reason.limit} tokens`)
+    }
+    // Optionally handle all the other reasons with a catch-all handler
+    // (reason) => Effect.succeed(`Unhandled reason: ${reason._tag}`)
+  )
+)
+
+export const unwrapAndHandle = callModel.pipe(
+  // Use `Effect.unwrapReason` to move the reasons into the error channel, then
+  // handle them all with `Effect.catchTags` or other error handling combinators
+  Effect.unwrapReason("AiError"),
+  Effect.catchTags({
+    RateLimitError: (reason) => Effect.succeed(`Back off for ${reason.retryAfter} seconds`),
+    QuotaExceededError: (reason) => Effect.succeed(`Increase quota beyond ${reason.limit}`),
+    SafetyBlockedError: (reason) => Effect.succeed(`Blocked by safety category: ${reason.category}`)
+  })
+)

package/ai-docs/src/01_effect/04_errors/index.md

@@ -0,0 +1 @@
+## Error handling

package/ai-docs/src/01_effect/05_resources/10_acquire-release.ts

@@ -0,0 +1,105 @@
+/**
+ * @title Acquiring resources with Effect.acquireRelease
+ *
+ * Define a service that uses `Effect.acquireRelease` to manage the lifecycle of
+ * a resource, ensuring that it is properly cleaned up when the service is no
+ * longer needed.
+ */
+import { Config, Context, Effect, Layer, Redacted, Schema } from "effect"
+import * as NodeMailer from "nodemailer"
+
+export class SmtpError extends Schema.Error<SmtpError>("SmtpError")({
+  cause: Schema.Defect()
+}) {}
+
+export class Smtp extends Context.Service<Smtp, {
+  send(message: {
+    readonly to: string
+    readonly subject: string
+    readonly body: string
+  }): Effect.Effect<void, SmtpError>
+}>()("app/Smtp") {
+  static readonly layer = Layer.effect(
+    Smtp,
+    Effect.gen(function*() {
+      const user = yield* Config.String("SMTP_USER")
+      const pass = yield* Config.Redacted("SMTP_PASS")
+
+      // Use `Effect.acquireRelease` to manage the lifecycle of the SMTP
+      // transporter.
+      //
+      // When the Layer is built, the transporter will be created. When the
+      // Layer is torn down, the transporter will be closed, ensuring that
+      // resources are always cleaned up properly.
+      const transporter = yield* Effect.acquireRelease(
+        Effect.sync(() =>
+          NodeMailer.createTransport({
+            host: "smtp.example.com",
+            port: 587,
+            secure: false,
+            auth: { user, pass: Redacted.value(pass) }
+          })
+        ),
+        (transporter) => Effect.sync(() => transporter.close())
+      )
+
+      const send = Effect.fn("Smtp.send")((message: {
+        readonly to: string
+        readonly subject: string
+        readonly body: string
+      }) =>
+        Effect.tryPromise({
+          try: () =>
+            transporter.sendMail({
+              from: "Acme Cloud <cloud@acme.com>",
+              to: message.to,
+              subject: message.subject,
+              text: message.body
+            }),
+          catch: (cause) => new SmtpError({ cause })
+        }).pipe(
+          Effect.asVoid
+        )
+      )
+
+      return Smtp.of({ send })
+    })
+  )
+}
+
+// We can then use the `Smtp` service in another service, and the transporter
+// will be properly managed by the Layer system.
+
+export class MailerError extends Schema.TaggedError<MailerError>()("MailerError", {
+  reason: SmtpError
+}) {}
+
+export class Mailer extends Context.Service<Mailer, {
+  sendWelcomeEmail(to: string): Effect.Effect<void, MailerError>
+}>()("app/Mailer") {
+  static readonly layerNoDeps = Layer.effect(
+    Mailer,
+    Effect.gen(function*() {
+      const smtp = yield* Smtp
+
+      const sendWelcomeEmail = Effect.fn("Mailer.sendWelcomeEmail")(function*(to: string) {
+        yield* smtp.send({
+          to,
+          subject: "Welcome to Acme Cloud!",
+          body: "Thanks for signing up for Acme Cloud. We're glad to have you!"
+        }).pipe(
+          Effect.mapError((reason) => new MailerError({ reason }))
+        )
+        yield* Effect.logInfo(`Sent welcome email to ${to}`)
+      })
+
+      return Mailer.of({ sendWelcomeEmail })
+    })
+  )
+
+  // Locally provide the Smtp layer to the Mailer layer, to eliminate all the
+  // requirements
+  static readonly layer = this.layerNoDeps.pipe(
+    Layer.provide(Smtp.layer)
+  )
+}

package/ai-docs/src/01_effect/05_resources/20_layer-side-effects.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Creating Layers that run background tasks
+ *
+ * Use Layer.effectDiscard to encapsulate background tasks without a service interface.
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect, Layer } from "effect"
+
+// Use Layer.effectDiscard when you want to create a layer that runs an effect
+// but does not provide any services.
+const BackgroundTask = Layer.effectDiscard(Effect.gen(function*() {
+  yield* Effect.logInfo("Starting background task...")
+
+  yield* Effect.gen(function*() {
+    while (true) {
+      yield* Effect.sleep("5 seconds")
+      yield* Effect.logInfo("Background task running...")
+    }
+  }).pipe(
+    Effect.onInterrupt(() => Effect.logInfo("Background task interrupted: layer scope closed")),
+    Effect.forkScoped
+  )
+}))
+
+// Run the background task layer. It will start when the layer is launched and
+// will be automatically interrupted when the layer scope is closed (e.g. when
+// the program exits).
+BackgroundTask.pipe(
+  Layer.launch,
+  NodeRuntime.runMain
+)