Effect Integration

Start with the Effect Quickstart for installation and a runnable first program. esix/effect supports Effect 3.21.3 and later 3.x versions. The Promise API remains available from esix without installing Effect.

Queries and missing records

Define a reusable model facade with const users = Esix.model(User) at module scope. Its operations return Effect<A, EsixOperationError, Esix> and resolve the database from the Layer provided at execution. If you already extracted the service with yield* Esix, db.model(User) remains available and returns operations without an additional environment requirement. Fluent methods return independent query descriptions: deriving one query never changes another. Every execution constructs a fresh query, and mutable query inputs are copied when the query is described. find, findBy, findOne, and first return Option<User>. An absent record is Option.none(), not a query failure.

import { BaseModel } from 'esix'
import { Esix } from 'esix/effect'
import { Effect, Option } from 'effect'

class User extends BaseModel {
  name = ''
  age = 0
}

const users = Esix.model(User)

export const findName = (id: string) =>
  Effect.gen(function* () {
    const found = yield* users.find(id)
    return Option.match(found, {
      onNone: () => 'Unknown user',
      onSome: (user) => user.name
    })
  })

Promise API	Effect facade
`await User.all()`	`yield* users.all()`
`await User.where('age', '>=', 18).get()`	`yield* users.where('age', '>=', 18).get()`
`await User.find(id)` → model or null	`yield* users.find(id)` → Option
`await user.save()`	`yield* users.save(user)`
`await user.update({ age: 31 })`	`yield* users.update(user, { age: 31 })`
`await user.delete()`	`yield* users.remove(user)`
`User.cursor(500)`	`users.stream(500)`

Filtering includes where, orWhere, membership/null checks, sorting, pagination, and text search. Terminal methods also include count, pluck, distinct, sum, average, min, max, percentile, aggregate, increment, decrement, and query delete. Field types and numeric increment restrictions are preserved. Raw query objects retain the existing sanitization rules.

Writes and relationships

create and firstOrCreate preserve model defaults and wasRecentlyCreated. Instance writes execute only when their Effect runs. Query delete() deletes matching records; remove(model) deletes one model.

import { BaseModel } from 'esix'
import { Esix } from 'esix/effect'
import { Effect } from 'effect'

class User extends BaseModel {
  name = ''
  age = 0
}
class Post extends BaseModel {
  userId = ''
  title = ''
}

const users = Esix.model(User)
const posts = Esix.model(Post)

export const createAuthor = Effect.gen(function* () {
  const author = yield* users.create({ name: 'Alice' })
  yield* users.update(author, { age: 31 })
  yield* posts.create({ userId: author.id, title: 'Hello' })
  return yield* users.hasMany(author, Post).get()
})

hasMany returns an Effect query; hasOne and belongsTo return Effects of Option. Their optional foreign/local/owner key arguments follow the relationship guide. Hydrated instances retain their database connection. Their original Promise methods, including relationship helpers, use that same connection. Custom methods remain Promise methods; the adapter does not rewrite them. Static methods such as User.find() continue using the default global connection. Saving a model through a facade for a different connection fails instead of moving the model silently. New, unbound instances can be saved through their facade.

Typed errors

EsixConnectionError describes Layer acquisition failure. Terminal operations fail with EsixOperationError, a union of:

Tag	Meaning
`EsixDuplicateKeyError`	MongoDB code 11000, such as a unique email constraint
`EsixTimeoutError`	A driver network/operation timeout or server time-limit error
`EsixModelBindingError`	The model has a different constructor or connection
`EsixQueryError`	Other query failures

Use Effect.catchTag to handle specific outcomes. Errors carry operation, collection, and an optional numeric MongoDB code. The original error is retained as the non-enumerable native cause; it is excluded from Schema encoding so arbitrary driver objects do not cross serialization boundaries. Generated messages omit driver text, which may contain credentials or document values. Treat raw causes as potentially sensitive if you log them.

import { BaseModel } from 'esix'
import { Esix } from 'esix/effect'
import { Effect } from 'effect'

class User extends BaseModel {
  name = ''
}

const users = Esix.model(User)

export const countUsers = Effect.gen(function* () {
  return yield* users.count().pipe(
    Effect.catchTag('EsixQueryError', (error) =>
      Effect.logError('User count failed', {
        operation: error.operation
      }).pipe(Effect.zipRight(Effect.fail(error)))
    )
  )
})

A timeout does not prove that a write was unapplied. There are no automatic retries. Apply retry policies deliberately, especially for writes that might have reached MongoDB before an error was returned. A client-close failure is retained as a finalizer defect.

Configuration and connection lifetime

Esix.layer({ url, database?, clientOptions? }) owns a native MongoDB client. The URL accepts a string or Redacted<string> and is held redacted internally. Options are explicit and do not change DB_URL, DB_DATABASE, or DB_ADAPTER used by the Promise API. Native Effect connections always use native driver behavior, even if the global adapter is set to mock. To read environment configuration with Effect:

import { Esix } from 'esix/effect'
import { Config } from 'effect'

export const EsixLive = Esix.layerConfig({
  url: Config.redacted('DB_URL'),
  clientOptions: Config.succeed({ maxPoolSize: 10 })
})

// Reads required DB_URL and optional DB_DATABASE.
export const EsixFromEnvironment = Esix.Default

layerConfig accepts Effect Config values for its options. Configuration failures remain typed ConfigErrors; missing DB_URL fails before a client is allocated. Plain layer continues to accept already-resolved options. Provide one Layer for the application’s lifetime. Owned connections close when their scope ends; captured models and queries cannot reopen a closed connection. Separate Layer instances own separate clients. For a client managed elsewhere, use Esix.layerFromDb(db); it never connects or closes the borrowed client’s resources.

Streaming

Use Stream combinators instead of a Promise callback to process batches:

import { BaseModel } from 'esix'
import { Esix } from 'esix/effect'
import { Effect, Stream } from 'effect'

class User extends BaseModel {
  name = ''
  age = 0
}

const users = Esix.model(User)

export const processAdults = Effect.gen(function* () {
  return yield* users
    .where('age', '>=', 18)
    .stream(500)
    .pipe(
      Stream.take(100),
      Stream.runForEach((user) => Effect.log(user.name))
    )
})

Streams use the existing keyset batch iteration: ascending id, homogeneous BSON id types, and no query sort/skip/limit. Use Stream.take to stop consumption. Each run gets a fresh iterator. Ending consumption closes the iterator and prevents further batches. Interruption cannot cancel or roll back an already-running MongoDB Promise. Iterator cleanup may wait for a pending batch; connection acquisition likewise settles before cleanup. Configure driver timeouts when bounded waits matter.

Testing with a borrowed database

Use a disposable database and provide it as a Layer. This example accepts a Db owned by the test fixture:

import { BaseModel } from 'esix'
import { Esix } from 'esix/effect'
import { Effect } from 'effect'
import type { Db } from 'mongodb'

class User extends BaseModel {
  name = ''
}

export const countInTestDatabase = (database: Db) =>
  Effect.runPromise(
    Effect.gen(function* () {
      return yield* Esix.model(User).count()
    }).pipe(Effect.provide(Esix.layerFromDb(database)))
  )

The test fixture remains responsible for cleaning its database and closing its client. Application services can also replace their repository dependencies with test Layers. See testing for the ordinary Promise API’s mock adapter.

In-process mock databases

Pass a Db opened by mongo-mock with Esix.layerFromDb(mockDb, { adapter: 'mock' }). The explicit adapter selects the existing mock-compatible BSON and aggregation paths; omitting it means a native MongoDB Db. The caller closes the mock Db after the test. This provides in-process tests without another connection-owning mock factory.

import { Esix } from 'esix/effect'
import type { Db } from 'mongodb'

export const mockLayer = (database: Db) =>
  Esix.layerFromDb(database, { adapter: 'mock' })

Runtime validation

Results are hydrated model instances, not Schema-decoded data. TypeScript field declarations and class defaults do not validate stored documents at runtime. Use Schema.decodeUnknown with your application’s schema at a boundary when runtime validation is required. Query sanitization protects query construction; it does not validate result shapes.

Getting Started

Models

Querying

Guides

Effect Integration

Queries and missing records

Writes and relationships

Typed errors

Configuration and connection lifetime

Streaming

Testing with a borrowed database

In-process mock databases

Runtime validation

​Queries and missing records

​Writes and relationships

​Typed errors

​Configuration and connection lifetime

​Streaming

​Testing with a borrowed database

​In-process mock databases

​Runtime validation

Queries and missing records

Writes and relationships

Typed errors

Configuration and connection lifetime

Streaming

Testing with a borrowed database

In-process mock databases

Runtime validation