/**
* @title Getting started with SQL
*
* Define a schema-backed domain model, run migrations against a SQLite
* database, and expose a derived repository through a service.
*/
import { NodeRuntime } from "@effect/platform-node"
import { SqliteClient, SqliteMigrator } from "@effect/sql-sqlite-node"
import { Context, Effect, Layer, Schema } from "effect"
import { Model } from "effect/schema"
import { SqlClient, SqlModel, SqlSchema } from "effect/sql"
// Use a branded string for the group id, so it cannot be mixed up with other
// string ids in the application.
export const GroupId = Schema.String.pipe(Schema.brand("GroupId"))
export type GroupId = typeof GroupId.Type
// `Model.Class` defines a domain model with variants for the database and JSON
// boundaries. The single field declaration is the source of truth, and each
// variant only contains the fields that make sense for that operation:
//
// - `Group` / `Group.insert` / `Group.update` for the database
// - `Group.json` / `Group.jsonCreate` / `Group.jsonUpdate` for JSON APIs
export class Group extends Model.Class<Group>("Group")({
// A UUID v4 primary key that is generated by the application on insert
id: Model.UuidV4Insert(GroupId),
name: Schema.NonEmptyString,
// `Model.FieldExcept` removes a field from the given variants. The slug is
// chosen when the group is created and is immutable afterwards, so it is
// removed from the update variants.
slug: Schema.NonEmptyString.pipe(Model.FieldExcept(["update", "jsonUpdate"])),
// `Model.FieldOnly` keeps a field in only the given variants. Internal notes
// live in the database and are never exposed through the JSON variants.
notes: Schema.NullOr(Schema.String).pipe(Model.FieldOnly(["select", "insert"])),
// `Model.Field` gives full control over the individual variants. The member
// count is maintained by the database, so the application can read it but
// never writes it.
memberCount: Model.Field({
select: Schema.Int,
json: Schema.Int
}),
// `createdAt` is set to the current time on insert, and `updatedAt` is
// refreshed on every update. Both are stored as strings, which suits SQLite.
createdAt: Model.DateTimeInsert,
updatedAt: Model.DateTimeUpdate
}) {}
export class GroupNotFound extends Schema.TaggedError<GroupNotFound>()("GroupNotFound", {
id: GroupId
}) {}
// The SqlClient layer determines which database you are talking to. Swap this
// layer for `@effect/sql-pg`, `@effect/sql-mysql2` etc. to target another
// database without changing the rest of the code.
const SqlLayer = SqliteClient.layer({ filename: ":memory:" })
// Migrations are effects keyed by `<id>_<name>` that run once, in id order. A
// real application would keep each migration in its own file and load them
// with `SqliteMigrator.fromFileSystem` instead of an inline record.
const MigratorLayer = SqliteMigrator.layer({
loader: SqliteMigrator.fromRecord({
"0001_create_groups": Effect.gen(function*() {
const sql = yield* SqlClient.SqlClient
yield* sql`
CREATE TABLE groups (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
slug TEXT NOT NULL,
notes TEXT,
memberCount INTEGER NOT NULL DEFAULT 0,
createdAt TEXT NOT NULL,
updatedAt TEXT NOT NULL
)
`
})
})
})
// Combine the database client with the migrations, so anything built on top of
// `SqlLive` sees a fully migrated database.
const SqlLive = MigratorLayer.pipe(Layer.provideMerge(SqlLayer))
// Wrap data access in a service, so the rest of the application depends on
// `Groups` instead of the database directly.
export class Groups extends Context.Service<Groups, {
create(name: string, slug: string): Effect.Effect<Group>
rename(id: GroupId, name: string): Effect.Effect<Group, GroupNotFound>
findById(id: GroupId): Effect.Effect<Group, GroupNotFound>
readonly list: Effect.Effect<Array<Group>>
}>()("app/Groups") {
static readonly layer = Layer.effect(
Groups,
Effect.gen(function*() {
const sql = yield* SqlClient.SqlClient
// `SqlModel.makeRepository` derives insert / update / findById / delete
// operations from the model, using the matching variant schema for each
// operation.
const repo = yield* SqlModel.makeRepository(Group, {
tableName: "groups",
spanPrefix: "Groups",
idColumn: "id"
})
// For queries the repository does not cover, combine the `sql` tag with
// `SqlSchema` to decode the rows using the model schema.
const listAll = SqlSchema.findAll({
Request: Schema.Void,
Result: Group,
execute: () => sql`SELECT * FROM groups ORDER BY createdAt`
})
// Use `Effect.fn` to give each method a named span for observability.
const create = Effect.fn("Groups.create")((name: string, slug: string) =>
// `Group.insert.makeEffect` fills in the generated id and timestamps
// using the Effect clock, so tests can control them with `TestClock`.
Group.insert.makeEffect({ name, slug, notes: null }).pipe(
Effect.flatMap(repo.insert),
// Database and encoding failures are unexpected here, so treat
// them as defects to keep the service interface focused on domain
// errors.
Effect.orDie
)
)
const rename = Effect.fn("Groups.rename")((id: GroupId, name: string) =>
Group.update.makeEffect({ id, name }).pipe(
Effect.flatMap(repo.update),
Effect.orDie
)
)
const findById = Effect.fn("Groups.findById")((id: GroupId) =>
repo.findById(id).pipe(
Effect.catchTags({
NoSuchElementError: () => new GroupNotFound({ id }),
SchemaError: Effect.die,
SqlError: Effect.die
})
)
)
const list = listAll().pipe(
Effect.orDie,
Effect.withSpan("Groups.list")
)
return Groups.of({ create, rename, findById, list })
})
).pipe(
// Provide the layers locally, so lots of messy wiring doesn't need to
// happen in the "main" entrypoint of the application.
Layer.provide(SqlLive)
)
}
const program = Effect.gen(function*() {
const groups = yield* Groups
const engineering = yield* groups.create("Engineering", "engineering")
const design = yield* groups.create("Design", "design")
yield* groups.rename(design.id, "Product Design")
const found = yield* groups.findById(engineering.id)
yield* Effect.log("found group", found)
const all = yield* groups.list
yield* Effect.log(`total groups: ${all.length}`)
})
program.pipe(
Effect.provide(Groups.layer),
NodeRuntime.runMain
)