@effectstream/db-emulator 0.100.14 → 0.100.16

package/README.md

@@ -1,34 +1,70 @@
 # @effectstream/db-emulator
 
-Database emulation utilities for Effectstream development and testing.
+A standalone migration runner for EffectStream's database. Apply the
+EffectStream system schema plus your migrations to a Postgres or PgLite
+instance without booting the full runtime — handy for unit tests and CI
+fixtures.
 
-## Purpose
+- Standalone migration runner: apply Effectstream's system schema + your migrations to a fresh DB.
+- For tests and CI fixtures; do not point at a production database.
+- Exists separately from `@effectstream/db` to break a circular dep with `@effectstream/sm`.
+- Single export: `standAloneApplyMigrations`.
 
-This package provides utilities for applying database migrations in test
-environments and during development. It was separated from `@effectstream/db` to break
-the circular dependency between `@effectstream/db` and `@effectstream/sm`.
+## Install
 
-## Dependencies
+```bash
+bun add @effectstream/db-emulator
+# or
+npm install @effectstream/db-emulator
+```
 
-- `@effectstream/db` - Core database functionality
-- `@effectstream/sm` - State machine primitives (for built-in primitives map)
+This package exists separately from `@effectstream/db` to break the
+circular dependency between `@effectstream/db` and `@effectstream/sm` —
+both of which `standAloneApplyMigrations` needs.
 
-## Usage
+## Standalone usage
 
 ```typescript
 import { getConnection } from "@effectstream/db";
 import { standAloneApplyMigrations } from "@effectstream/db-emulator";
+import { localhostConfig } from "./config.ts";
+import { migrationTable } from "./migrations.ts";
 
 const db = await getConnection();
 await standAloneApplyMigrations(
   db,
   migrationTable,
   localhostConfig,
-  userDefinedPrimitives, // optional
+  /* userDefinedPrimitives */ undefined,
 );
 ```
 
-## Note
+You're left with a database that has every EffectStream system table
+plus your migrations applied, ready for tests to read and write
+directly against the client returned by `getConnection()`.
+
+> Use only against ephemeral / in-memory databases. The function
+> assumes it owns the schema.
+
+## Inside EffectStream
+
+Designed for use in tests and migration tooling. Pair with
+[`@effectstream/db/start-pglite`](https://www.npmjs.com/package/@effectstream/db)
+for a quick in-memory database that's ready for app code to read /
+write.
+
+## Key exports
+
+- `standAloneApplyMigrations(db, migrationTable, config, userPrimitives?)` — apply the EffectStream system migrations plus your own, against the given pg client.
+
+## Examples
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+For the broader migration pattern, see
+`templates/*/packages/client/database/sql-to-ts.ts`.
+
+## Links
 
-This is primarily a development/testing utility. Production applications
-typically use the migration system directly through `@effectstream/db`.
+- Docs: https://effectstream.github.io/docs/packages/node/db-emulator
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/node-sdk/db-emulator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/db-emulator",
-  "version": "0.100.14",
+  "version": "0.100.16",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {

package/test/examples.test.ts

@@ -0,0 +1,8 @@
+// Examples for the README — verify the public surface resolves.
+
+import { test, expect } from "bun:test";
+import { standAloneApplyMigrations } from "../mod.ts";
+
+test("README: standAloneApplyMigrations is exported as a function", () => {
+  expect(typeof standAloneApplyMigrations).toBe("function");
+});