effect-cf

KO | EN

gitlite — search

#react #ai #typescript #go #machine-learning #rust #docker #java #awesome #cli #awesome-list #pytorch #security #mcp

(★ 18)

Typed Effect clients for Cloudflare Workers with schema validation.

effect-cf Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# effect-cf

Typed Effect clients for Cloudflare Workers with schema validation.

## Modules

| Module                                           | Description                            | Import                                                        |
| ------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------- |
| [core](src/core/README.md)                       | Shared errors and schema helpers       | `import * as Core from "effect-cf/core"`                      |
| [kv](src/kv/README.md)                           | KV client with type-safe operations    | `import * as KV from "effect-cf/kv"`                          |
| [cache](src/cache/README.md)                     | Cache client with JSON support         | `import * as Cache from "effect-cf/cache"`                    |
| [durable-objects](src/durable-objects/README.md) | Full Durable Objects (server + client) | `import * as DurableObjects from "effect-cf/durable-objects"` |
| [r2](src/r2/README.md)                           | R2 object storage (S3-compatible)      | `import * as R2 from "effect-cf/r2"`                          |
| [d1](src/d1/README.md)                           | D1 SQLite database                     | `import * as D1 from "effect-cf/d1"`                          |
| [workers](src/workers/README.md)                 | Workers runtime utilities              | `import * as Workers from "effect-cf/workers"`                |
| [queues](src/queues/README.md)                   | Message queues for async processing    | `import * as Queue from "effect-cf/queues"`                   |
| [ai-gateway](src/ai-gateway/README.md)           | AI model inference gateway             | `import * as AIGateway from "effect-cf/ai-gateway"`           |
| [vectorize](src/vectorize/README.md)             | Vector database for AI/ML              | `import * as Vectorize from "effect-cf/vectorize"`            |
| [hyperdrive](src/hyperdrive/README.md)           | Database connection pooling            | `import * as Hyperdrive from "effect-cf/hyperdrive"`          |
| [testing](src/testing/README.md)                 | Test utilities with Miniflare          | `import * as Testing from "effect-cf/testing"`                |

## Installation

```bash
npm install effect-cf
# or
pnpm add effect-cf
# or
yarn add effect-cf
```

## Design Philosophy

- **Namespaced APIs**: Every service is accessible through its own namespace (`KV`, `Cache`, `DurableObjects`, `R2`, `D1`)
- **Type Safety**: Full schema validation via `@effect/schema`
- **Ergonomic**: Factory functions for direct use, Layers for Effect dependency injection
- **Explicit**: No magic, everything is typed and predictable
- **Complete**: Both client-side (calling services) and server-side (implementing services) support

## Quick Example

```typescript
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "@effect/schema/Schema";
import * as KV from "effect-cf/kv";

const User = Schema.Struct({
  id: Schema.String,
  name: Schema.String
});

// Method 1: Direct factory usage
const kv = KV.make({
  type: "json",
  namespace: env.KV_USERS,
  schema: User
});

const program = Effect.gen(function* () {
  yield* kv.put("user:1", { id: "1", name: "Ada" });
  const user = yield* kv.getOrFail("user:1");
  return user;
});

// Method 2: Service accessors with Layer
const program2 = Effect.gen(function* () {
  yield* KV.put("user:1", { id: "1", name: "Ada" });
  const user = yield* KV.getOrFail("user:1");
  return user;
});

const runnable = program2.pipe(
  Effect.provide(KV.layer({ type: "json", namespace: env.KV_USERS, schema: User }))
);

Effect.runPromise(runnable);
```

## Complete Application Example

```typescript
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "@effect/schema/Schema";
import * as Workers from "effect-cf/workers";
import * as KV from "effect-cf/kv";
import * as D1 from "effect-cf/d1";
import * as R2 from "effect-cf/r2";

const User = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  avatar: Schema.String
});

// Worker handler using multiple services
const handler = (request: Request, env: Env) =>
  Effect.gen(function* () {
    const url = new URL(request.url);

if (url.pathname === "/api/users") {
      // Store metadata in D1
      const user = yield* D1.queryFirst<User>(
        "SELECT * FROM users WHERE id = ?",
        url.searchParams.get("id")
      );

if (!user) {
        return new Response("Not found", { status: 404 });
      }

// Fetch avatar from R2
      const avatar = yield* R2.getOrFail(user.avatar);

// Cache the response
      yield* Workers.waitUntil(
        Effect.gen(function* () {
          yield* KV.put(`cache:${user.id}`, user);
        })
      );

return Response.json(user);
    }

return new Response("Not found", { status: 404 });
  });

// Export worker
export default Workers.serve(handler);

// Or with Layer composition
const AppLayer = Layer.mergeAll(
  KV.layer({ type: "json", namespace: env.KV, schema: User }),
  D1.layer(env.DB),
  R2.layer(env.R2_BUCKET)
);

export default Workers.serve((req, env) => Effect.provide(handler(req, env), AppLayer));
```

## Durable Objects Server Example

```typescript
import * as DurableObjects from "effect-cf/durable-objects";
import * as Effect from "effect/Effect";

// Implement a counter DO
export class Counter extends DurableObjects.EffectDurableObject {
  fetch(request: Request) {
    return Effect.gen(function* () {
      const url = new URL(request.url);

if (url.pathname === "/increment") {
        const current = (yield* this.storage.get<number>("count")) ?? 0;
        yield* this.storage.put("count", current + 1);
        return new Response(String(current + 1));
      }

const count = (yield* this.storage.get<number>("count")) ?? 0;
      return new Response(String(count));
    });
  }
}
```

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
```

## API Pattern

All modules follow a consistent pattern:

| Export             | Purpose            | Example                    |
| ------------------ | ------------------ | -------------------------- |
| `make()`           | Factory function   | `KV.make({...})`           |
| `layer()`          | Effect Layer       | `KV.layer({...})`          |
| `Tag`              | Service identifier | `KV.KvTag`                 |
| `get`, `put`, etc. | Service accessors  | `KV.get`, `KV.put`         |
| `Types`            | Type namespace     | `KV.Types.KvNamespaceLike` |

## Service-Specific Patterns

### Storage Services (KV, R2, D1, Cache)

- `get(key)` → `Effect<A \| null, Error>`
- `getOrFail(key)` → `Effect<A, Error>` (throws NotFoundError)
- `put(key, value)` → `Effect<void, Error>`
- `delete(key)` → `Effect<void, Error>`

### Durable Objects

- `EffectDurableObject` base class for implementing DOs
- `fetch(request)` → `Effect<Response, Error>`
- `alarm()` → `Effect<void, Error>` (optional)
- `storage` → Effect-wrapped storage API

### Workers Runtime

- `serve(handler)` → Creates ExportedHandler
- `waitUntil(effect)` → Background task execution
- `passThroughOnException()` → Error passthrough

## License

MIT

effect-cf

effect-cf Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

effect-cf

effect-cf Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README