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

package/ai-docs/src/50_http-client/10_basics.ts

@@ -0,0 +1,102 @@
+/**
+ * @title Getting started with HttpClient
+ *
+ * Define a service that uses the HttpClient module to fetch data from an external API
+ */
+import { Context, Effect, flow, Layer, Schedule, Schema } from "effect"
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+
+class Todo extends Schema.Class<Todo>("Todo")({
+  userId: Schema.Int,
+  id: Schema.Int,
+  title: Schema.String,
+  completed: Schema.Boolean
+}) {}
+
+export class JsonPlaceholder extends Context.Service<JsonPlaceholder, {
+  readonly allTodos: Effect.Effect<ReadonlyArray<Todo>, JsonPlaceholderError>
+  getTodo(id: number): Effect.Effect<Todo, JsonPlaceholderError>
+  createTodo(todo: Omit<Todo, "id">): Effect.Effect<Todo, JsonPlaceholderError>
+}>()("app/JsonPlaceholder") {
+  static readonly layer = Layer.effect(
+    JsonPlaceholder,
+    Effect.gen(function*() {
+      // Access the HttpClient service, and apply some common middleware to all
+      // requests:
+      const client = (yield* HttpClient.HttpClient).pipe(
+        // Add a base URL to all requests made with this client, and set the
+        // Accept header to expect JSON responses
+        HttpClient.mapRequest(flow(
+          HttpClientRequest.prependUrl("https://jsonplaceholder.typicode.com"),
+          HttpClientRequest.acceptJson
+        )),
+        // Fail if the response status is not 2xx
+        HttpClient.filterStatusOk,
+        // Retry transient errors (network issues, 5xx responses) with an
+        // exponential backoff.
+        //
+        // See the schedule documentation for more complex retry strategies.
+        HttpClient.retryTransient({
+          schedule: Schedule.exponential(100),
+          times: 3
+        })
+      )
+
+      const allTodos = client.get("/todos").pipe(
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(Schema.Array(Todo))),
+        Effect.mapError((cause) => new JsonPlaceholderError({ cause })),
+        Effect.withSpan("JsonPlaceholder.allTodos")
+      )
+
+      // Use the HttpClient to fetch a todo item by id, and decode the response
+      // using the Todo schema.
+      const getTodo = Effect.fn("JsonPlaceholder.getTodo")(function*(id: number) {
+        // Annotate the current span with the id of the todo being fetched, so
+        // that it shows up in telemetry for this request.
+        yield* Effect.annotateCurrentSpan({ id })
+
+        const todo = yield* client.get(`/todos/${id}`, {
+          // You can pass additional options to individual requests.
+          // There are options for query parameters, request body, headers, and
+          // more.
+          urlParams: { format: "json" }
+        }).pipe(
+          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
+          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
+        )
+
+        return todo
+      })
+
+      // You can use the HttpClientRequest module to build up more complex
+      // requests:
+      const createTodo = Effect.fn("JsonPlaceholder.createTodo")(function*(todo: Omit<Todo, "id">) {
+        yield* Effect.annotateCurrentSpan({ title: todo.title })
+
+        const createdTodo = yield* HttpClientRequest.post("/todos").pipe(
+          // The HttpClientRequest module has many helper functions for building requests.
+          HttpClientRequest.setUrlParams({ format: "json" }),
+          HttpClientRequest.bodyJsonUnsafe(todo),
+          client.execute,
+          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
+          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
+        )
+
+        return createdTodo
+      })
+
+      return JsonPlaceholder.of({
+        allTodos,
+        getTodo,
+        createTodo
+      })
+    })
+  ).pipe(
+    // Provide the fetch-based HttpClient implementation
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+export class JsonPlaceholderError extends Schema.TaggedError<JsonPlaceholderError>()("JsonPlaceholderError", {
+  cause: Schema.Defect()
+}) {}

package/ai-docs/src/50_http-client/index.md

@@ -0,0 +1,3 @@
+## Effect HttpClient
+
+Build http clients with the `HttpClient` module.

package/ai-docs/src/51_http-server/10_basics.ts

@@ -0,0 +1,116 @@
+/**
+ * @title Getting started with HttpApi
+ *
+ * Define a schema-first API, implement handlers, secure endpoints with
+ * middleware, serve it over HTTP, and call it using a generated typed client.
+ */
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+import { Context, Effect, flow, Layer, Schedule } from "effect"
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpRouter, HttpServer } from "effect/unstable/http"
+import { HttpApiBuilder, HttpApiClient, HttpApiMiddleware, HttpApiScalar } from "effect/unstable/httpapi"
+import { createServer } from "node:http"
+// Api definitions should **always** be seperate from the server implementation,
+// so that they can be shared between the server and client without leaking
+// server code into clients.
+// Ideally, the would use a seperate package in a monorepo.
+import { Api } from "./fixtures/api/Api.ts"
+import { Authorization } from "./fixtures/api/Authorization.ts"
+import { UsersApiHandlers } from "./fixtures/server/Users/http.ts"
+
+// This walkthrough focuses on runtime wiring and typed client usage.
+// See the fixture files for the API schemas, endpoint definitions and handlers:
+
+const SystemApiHandlers = HttpApiBuilder.group(
+  Api,
+  "system",
+  Effect.fn(function*(handlers) {
+    return handlers.handle("health", () => Effect.void)
+  })
+)
+
+const ApiRoutes = HttpApiBuilder.layer(Api, {
+  openapiPath: "/openapi.json"
+}).pipe(
+  // Provide all the handler Layers for the API.
+  Layer.provide([UsersApiHandlers, SystemApiHandlers])
+)
+
+// Define a /docs route that serves scalar documentation
+const DocsRoute = HttpApiScalar.layer(Api, {
+  path: "/docs"
+})
+
+// Merge all the http routes together
+const AllRoutes = Layer.mergeAll(ApiRoutes, DocsRoute)
+
+// Create an HTTP server Layer that serves the API routes.
+//
+// Here we are using the NodeHttpServer, but you could also use the
+// BunHttpServer
+export const HttpServerLayer = HttpRouter.serve(AllRoutes).pipe(
+  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 }))
+)
+
+// Then run the server using Layer.launch
+Layer.launch(HttpServerLayer).pipe(
+  NodeRuntime.runMain
+)
+
+// Or create a web handler, which can be used in serverless environments
+export const { handler, dispose } = HttpRouter.toWebHandler(AllRoutes.pipe(
+  Layer.provide(HttpServer.layerServices)
+))
+
+// -----------------
+// Client side setup
+// -----------------
+
+export const AuthorizationClient = HttpApiMiddleware.layerClient(
+  Authorization,
+  Effect.fn(function*({ next, request }) {
+    // Here you can modify the request and pass it down the middleware chain.
+    // This is where you would add authentication tokens, custom headers, etc.
+    // For this example, we just add a hardcoded bearer token to all requests.
+    return yield* next(HttpClientRequest.bearerToken(request, "dev-token"))
+  })
+)
+
+// Define the HttpApiClient service, which will be used to make requests to the
+// API.
+export class ApiClient extends Context.Service<ApiClient, HttpApiClient.ForApi<typeof Api>>()("acme/ApiClient") {
+  static readonly layer = Layer.effect(
+    ApiClient,
+    HttpApiClient.make(Api, {
+      // Use transformClient to apply middleware to the generated client. This
+      // is useful for settings the base url and applying retry policies.
+      transformClient: (client) =>
+        client.pipe(
+          HttpClient.mapRequest(flow(
+            HttpClientRequest.prependUrl("http://localhost:3000")
+          )),
+          HttpClient.retryTransient({
+            schedule: Schedule.exponential(100),
+            times: 3
+          })
+        )
+    })
+  ).pipe(
+    // Provide the client implementation of the Authorization middleware, which
+    // is required.
+    Layer.provide(AuthorizationClient),
+    // Supply a HttpClient implementation to use for making requests. Here we
+    // use the FetchHttpClient, but you could also use the NodeHttpClient or
+    // BunHttpClient.
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+// The generated client mirrors your API definition, so renames and schema
+// changes are checked end-to-end at compile time.
+export const callApi = Effect.gen(function*() {
+  const client = yield* ApiClient
+
+  yield* client.health()
+}).pipe(
+  Effect.provide(ApiClient.layer)
+)

package/ai-docs/src/51_http-server/fixtures/api/Api.ts

@@ -0,0 +1,14 @@
+import { HttpApi, OpenApi } from "effect/unstable/httpapi"
+import { SystemApi } from "./System.ts"
+import { UsersApiGroup } from "./Users.ts"
+
+// Defined the root API, which combines all of the groups together. This is the
+// API that you will serve and generate clients for. You can also annotate the
+// API with OpenAPI metadata.
+export class Api extends HttpApi.make("user-api")
+  .add(UsersApiGroup)
+  .add(SystemApi)
+  .annotateMerge(OpenApi.annotations({
+    title: "Acme User API"
+  }))
+{}

package/ai-docs/src/51_http-server/fixtures/api/Authorization.ts

@@ -0,0 +1,36 @@
+import { Context, Schema } from "effect"
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi"
+import type { User } from "../domain/User.ts"
+
+export class CurrentUser extends Context.Service<CurrentUser, User>()("acme/HttpApi/Authorization/CurrentUser") {}
+
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
+  "Unauthorized",
+  {
+    message: Schema.String
+  },
+  // You can define error status codes directly on the error class
+  { httpApiStatus: 401 }
+) {}
+
+export class Authorization extends HttpApiMiddleware.Service<Authorization, {
+  // Middleware can provide services to other middleware and endpoints, which is
+  // useful for things like authentication, where you want to inject the current
+  // user into the context for other endpoints to consume.
+  provides: CurrentUser
+  // If your middleware requires dependencies from other middleware, you can
+  // specify those as well.
+  requires: never
+}>()("acme/HttpApi/Authorization", {
+  // This middleware requires clients to also provide an implementation, to
+  // inject a api key
+  requiredForClient: true,
+  // Middleware can optionally define security schemes, which are used to
+  // generate OpenAPI docs and decode credientials from incoming requests for
+  // you.
+  security: {
+    bearer: HttpApiSecurity.bearer
+  },
+  // Middlware can specify errors that it may raise
+  error: Unauthorized
+}) {}

package/ai-docs/src/51_http-server/fixtures/api/System.ts

@@ -0,0 +1,10 @@
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi"
+
+// Top level groups are added to the root of the derived HttpApiClient.
+//
+// `client.health()`
+export class SystemApi extends HttpApiGroup.make("system", { topLevel: true }).add(
+  HttpApiEndpoint.get("health", "/health", {
+    success: HttpApiSchema.NoContent
+  })
+) {}

package/ai-docs/src/51_http-server/fixtures/api/Users.ts

@@ -0,0 +1,91 @@
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { User, UserId } from "../domain/User.ts"
+import { SearchQueryTooShort, UserNotFound } from "../domain/UserErrors.ts"
+import { Authorization } from "./Authorization.ts"
+
+export class UsersApiGroup extends HttpApiGroup.make("users")
+  .add(
+    HttpApiEndpoint.get("list", "/", {
+      query: {
+        search: Schema.optional(Schema.String)
+      },
+      success: Schema.Array(User)
+    }),
+    HttpApiEndpoint.get("search", "/search", {
+      // For get requests, payload uses the query string
+      payload: {
+        search: Schema.String
+      },
+      success: [
+        Schema.Array(User),
+        Schema.String.pipe(HttpApiSchema.asText({
+          contentType: "text/csv"
+        }))
+      ],
+      error: [
+        SearchQueryTooShort.pipe(
+          // If you want an error to return no content, you can use
+          // `HttpApiSchema.asNoContent` and provide a decoder that transforms the
+          // error into the appropriate type.
+          HttpApiSchema.asNoContent({
+            decode: () => new SearchQueryTooShort()
+          })
+        ),
+        // You can also add some of the built in `HttpApiError`s to handle common
+        // error cases like bad requests, unauthorized, etc.
+        HttpApiError.RequestTimeoutNoContent
+      ]
+    }),
+    HttpApiEndpoint.get("getById", "/:id", {
+      params: {
+        // Path parameter schemas need to be able to decode from strings.
+        // Schema.decodeTo can be used to "bridge" between schemas
+        id: Schema.FiniteFromString.pipe(
+          Schema.decodeTo(UserId)
+        )
+      },
+      success: User,
+      error: UserNotFound.pipe(
+        // If you want an error to return no content, you can use
+        // `HttpApiSchema.asNoContent` and provide a decoder that transforms the
+        // error into the appropriate type.
+        HttpApiSchema.asNoContent({
+          decode: () => new UserNotFound()
+        })
+      )
+    }),
+    HttpApiEndpoint.post("create", "/", {
+      // For post requests, payload uses the request body. It defaults to JSON,
+      // but you can specify other content types as well using
+      // `HttpApiSchema.asText`, `HttpApiSchema.asMultipart`, etc.
+      payload: Schema.Struct({
+        name: Schema.String,
+        email: Schema.String
+      }),
+      success: User
+    }),
+    HttpApiEndpoint.get("me", "/me", {
+      success: User,
+      error: UserNotFound.pipe(HttpApiSchema.status(404))
+    })
+  )
+  // You can apply middleware to entire groups, which is useful for things like
+  // authentication and authorization.
+  //
+  // You can also apply middleware to individual endpoints if you need more
+  // fine-grained control.
+  .middleware(Authorization)
+  // To add a common prefix to all endpoints in a group, you can use the `prefix`
+  // method. This is useful for grouping related endpoints together under a common
+  // path segment. In this case, all endpoints in the `UsersApiGroup` will be
+  // prefixed with `/users`.
+  .prefix("/users")
+  // You can add OpenAPI annotations to groups, endpoints, and even parameters and
+  // request bodies. These will be merged together to generate the final OpenAPI
+  // docs for the API
+  .annotateMerge(OpenApi.annotations({
+    title: "Users",
+    description: "User management endpoints"
+  }))
+{}

package/ai-docs/src/51_http-server/fixtures/domain/User.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect"
+
+export const UserId = Schema.Int.pipe(
+  Schema.brand("UserId")
+)
+export type UserId = typeof UserId.Type
+
+export class User extends Schema.Class<User>("User")({
+  id: UserId,
+  name: Schema.String,
+  email: Schema.String
+}) {}

package/ai-docs/src/51_http-server/fixtures/domain/UserErrors.ts

@@ -0,0 +1,22 @@
+import { Schema } from "effect"
+
+export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+  "UserNotFound",
+  {},
+  // You can specify the status code for this error inline
+  { httpApiStatus: 404 }
+) {}
+
+export class SearchQueryTooShort
+  extends Schema.TaggedError<SearchQueryTooShort>()("SearchQueryTooShort", {}, { httpApiStatus: 422 })
+{
+  static readonly minimumLength = 2
+}
+
+// Create a wrapper error class for all errors in the Users API.
+//
+// This prevents adding too many error types to services / endpoint definitions.
+//
+export class UsersError extends Schema.TaggedError<UsersError>()("UsersError", {
+  reason: Schema.Union([UserNotFound, SearchQueryTooShort])
+}) {}

package/ai-docs/src/51_http-server/fixtures/server/Authorization.ts

@@ -0,0 +1,36 @@
+import { Effect, Layer, Redacted } from "effect"
+import { Authorization, CurrentUser, Unauthorized } from "../api/Authorization.ts"
+import { User, UserId } from "../domain/User.ts"
+
+// The implementation of the Authorization middleware. It is seperate from the
+// service definition to avoid leaking it into a client.
+export const AuthorizationLayer = Layer.effect(
+  Authorization,
+  Effect.gen(function*() {
+    // Here you could access services required by the middleware, like a
+    // database or an external auth provider.
+    yield* Effect.logInfo("Starting Authorization middleware")
+
+    return Authorization.of({
+      bearer: Effect.fn(function*(httpEffect, { credential }) {
+        // Validate the token and return an Unauthorized error if it's invalid.
+        const token = Redacted.value(credential)
+        if (token !== "dev-token") {
+          return yield* new Unauthorized({ message: "Missing or invalid bearer token" })
+        }
+
+        // Provide the current user to the rest of the stack. This will be
+        // available in any endpoint or middleware that runs after this one.
+        return yield* Effect.provideService(
+          httpEffect,
+          CurrentUser,
+          new User({
+            id: UserId.make(1),
+            name: "Dev User",
+            email: "dev@acme.com"
+          })
+        )
+      })
+    })
+  })
+)

package/ai-docs/src/51_http-server/fixtures/server/Users/http.ts

@@ -0,0 +1,71 @@
+import { Effect, Layer } from "effect"
+import { HttpApiBuilder, HttpApiError } from "effect/unstable/httpapi"
+import { Api } from "../../api/Api.ts"
+import { CurrentUser } from "../../api/Authorization.ts"
+import { AuthorizationLayer } from "../Authorization.ts"
+import { Users } from "../Users.ts"
+
+export const UsersApiHandlers = HttpApiBuilder.group(
+  Api,
+  "users",
+  Effect.fn(function*(handlers) {
+    const users = yield* Users
+
+    return handlers
+      .handle("list", ({ query }) =>
+        users.list(query.search).pipe(
+          // The list endpoint expects no errors, so we convert any potential
+          // errors into a 500 Internal Server Error.
+          Effect.orDie
+        ))
+      .handle(
+        "search",
+        Effect.fn(function*({ payload }) {
+          if (payload.search === "bad-request") {
+            // You can use the built in error types like any other
+            // Schema.TaggedError
+            return yield* new HttpApiError.RequestTimeout()
+          }
+          return yield* users.list(payload.search).pipe(
+            Effect.catchReason(
+              "UsersError",
+              "SearchQueryTooShort",
+              // Re-fail the "SearchQueryTooShort" reason
+              Effect.fail,
+              // All other reasons are unexpected, so we convert them into a 500
+              // Internal Server Error.
+              Effect.die
+            )
+          )
+        })
+      )
+      .handle("getById", ({ params }) =>
+        users.getById(params.id).pipe(
+          // You can also use Effect.catchReasons to handle multiple error
+          // reasons at once
+          Effect.catchReasons("UsersError", {
+            UserNotFound: (e) => Effect.fail(e)
+          }, Effect.die)
+        ))
+      .handle("create", ({ payload }) =>
+        users.create(payload).pipe(
+          Effect.orDie
+          // You could alse use Effect.unwrapReason to moves rror reasons up to
+          // the top level, so you can handle them with Effect.catch or
+          // Effect.catchTag etc.
+          //
+          // Effect.unwrapReason("UsersError"),
+          // Effect.catchTags({
+          //   UserNotFound: Effect.die,
+          //   SearchQueryTooShort: Effect.die
+          // })
+        ))
+      .handle("me", () =>
+        // The Authorization middleware provides the CurrentUser service, so we
+        // can access it here.
+        CurrentUser)
+  })
+).pipe(
+  // Provide the dependencies for the handlers.
+  Layer.provide([Users.layer, AuthorizationLayer])
+)

package/ai-docs/src/51_http-server/fixtures/server/Users.ts

@@ -0,0 +1,62 @@
+import { Context, Effect, Layer, Ref } from "effect"
+import { User, UserId } from "../domain/User.ts"
+import { SearchQueryTooShort, UserNotFound, UsersError } from "../domain/UserErrors.ts"
+
+export class Users extends Context.Service<Users, {
+  list(search: string | undefined): Effect.Effect<Array<User>, UsersError>
+  getById(id: UserId): Effect.Effect<User, UsersError>
+  create(input: { readonly name: string; readonly email: string }): Effect.Effect<User, UsersError>
+}>()("acme/Users") {
+  static readonly layer = Layer.effect(
+    Users,
+    Effect.gen(function*() {
+      const users = new Map<number, User>([
+        [
+          1,
+          new User({
+            id: UserId.make(1),
+            name: "Admin",
+            email: "admin@acme.dev"
+          })
+        ]
+      ])
+      const nextId = yield* Ref.make(2)
+
+      const list = Effect.fn("UsersRepo.list")(function*(search: string | undefined) {
+        const allUsers = Array.from(users.values())
+        if (search === undefined || search.length === 0) {
+          return allUsers
+        } else if (search.length < SearchQueryTooShort.minimumLength) {
+          return yield* new UsersError({
+            reason: new SearchQueryTooShort()
+          })
+        }
+        yield* Effect.annotateCurrentSpan({ search })
+        const normalized = search.toLowerCase()
+        return allUsers.filter((user) =>
+          user.name.toLowerCase().includes(normalized) || user.email.toLowerCase().includes(normalized)
+        )
+      })
+
+      const getById = Effect.fn("UsersRepo.getById")(function*(id: UserId) {
+        yield* Effect.annotateCurrentSpan({ id })
+        const user = users.get(id)
+        if (user === undefined) {
+          return yield* new UsersError({
+            reason: new UserNotFound()
+          })
+        }
+        return user
+      })
+
+      const create = Effect.fn("UsersRepo.create")(function*(input: { readonly name: string; readonly email: string }) {
+        const id = yield* Ref.getAndUpdate(nextId, (current) => current + 1)
+        const user = new User({ id: UserId.make(id), ...input })
+        users.set(user.id, user)
+        return user
+      })
+
+      return Users.of({ list, getById, create })
+    })
+  )
+}

package/ai-docs/src/51_http-server/index.md

@@ -0,0 +1,3 @@
+## Building HttpApi servers
+
+`HttpApi` gives you schema-first, type-safe HTTP APIs with runtime validation, typed clients, and OpenAPI docs from one definition.