boundlessdb 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to BoundlessDB will be documented in this file.
+
+## [Unreleased]
+
+### Breaking Changes
+
+#### Removed: Token/Cryptographic Signing
+- Removed `token.ts` and `token.browser.ts`
+- Removed `secret` option from `EventStoreOptions`
+- **Migration:** Use `appendCondition` directly (see below)
+
+#### Removed: Decider Pattern Helpers
+- Removed `src/decider.ts` with `Decider` type, `evolve()` and `decide()` helpers
+- **Migration:** Use plain functions with standard `reduce`:
+  ```typescript
+  // Before
+  const state = evolve(events, decider);
+  const newEvents = decide(command, state, decider);
+  
+  // After
+  const state = events.reduce(evolve, initialState);
+  const newEvents = decide(command, state);
+  ```
+
+#### Changed: Token → AppendCondition
+- `read()` now returns `appendCondition` as a plain object (not encoded token)
+- `append()` accepts `AppendCondition` directly
+- **Migration:**
+  ```typescript
+  // Before
+  const { events, token } = await store.read({ conditions });
+  await store.append(newEvents, token);
+  
+  // After  
+  const { events, appendCondition } = await store.read({ conditions });
+  await store.append(newEvents, appendCondition);
+  ```
+
+### Added
+
+#### QueryResult Class
+- `read()` returns a `QueryResult` with helper methods:
+  - `isEmpty()`, `count`, `first()`, `last()`
+  - `position`, `conditions`, `appendCondition`
+
+#### Typed Events
+- `Event<Type, Payload>` marker type for type-safe events
+- `read<E>()` and `append<E>()` support generics
+
+#### Union Types for QueryCondition
+- `UnconstrainedCondition`: `{ type: 'X' }` — match all events of type
+- `ConstrainedCondition`: `{ type: 'X', key: 'a', value: 'b' }` — match specific key
+- Partial conditions like `{ type: 'X', key: 'a' }` are now TypeScript errors
+
+#### Type Guard
+- `isConstrainedCondition()` exported for storage implementations
+
+#### Fluent Query API
+- Chainable query builder: `store.query<E>()`
+- Methods: `matchType()`, `matchKey()`, `fromPosition()`, `limit()`, `read()`
+  ```typescript
+  const { events, appendCondition } = await store.query<CourseEvent>()
+    .matchType('CourseCreated')
+    .matchKey('StudentSubscribed', 'course', 'cs101')
+    .read();
+  ```
+
+### Changed
+
+- Empty `conditions: []` now returns all events (was: error)
+- `appendCondition` is a plain object: `{ position: bigint, conditions: QueryCondition[] }`
+
+### Documentation
+
+- Landing page redesigned with tabbed code examples
+- README updated to use `decide` pattern
+- Removed npm install section (package not yet published)
+
+## [0.1.0] - 2026-02-20
+
+### Added
+
+- Initial release
+- DCB-inspired Event Store with config-based consistency keys
+- Storage backends: SQLite, PostgreSQL, sql.js (browser), In-Memory
+- Auto-reindex on config change
+- Conflict detection with delta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Bortz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,545 @@
+# BoundlessDB
+
+A **DCB-inspired** event store library for TypeScript.
+
+> *BoundlessDB* — because consistency boundaries should be dynamic, not fixed.
+
+## 🎉 Try it Live!
+
+**[Interactive Browser Demo](https://boundlessdb.dev/demo.html)** — No installation required!
+
+The entire event store runs client-side in your browser using WebAssembly SQLite.
+
+## Features
+
+- 🚀 **Works in Browser** — Full client-side event sourcing via sql.js (WASM)
+- 🔑 **No Streams** — Events organized via configurable consistency keys
+- ⚙️ **Config-based Key Extraction** — Events remain pure business data
+- 🎟️ **AppendCondition** — Simple, transparent optimistic concurrency control
+- ⚡ **Conflict Detection with Delta** — Get exactly what changed since your read
+- 🔄 **Auto-Reindex** — Change your config, keys are automatically rebuilt
+- 💾 **SQLite, PostgreSQL & In-Memory** — Multiple storage backends
+- 📦 **Embedded Library** — No separate server, runs in your process
+
+## Quick Start
+
+```typescript
+import { createEventStore, SqliteStorage } from 'boundlessdb';
+
+const store = createEventStore({
+  storage: new SqliteStorage(':memory:'),
+  consistency: {
+    eventTypes: {
+      CourseCreated: {
+        keys: [{ name: 'course', path: 'data.courseId' }]
+      },
+      StudentSubscribed: {
+        keys: [
+          { name: 'course', path: 'data.courseId' },
+          { name: 'student', path: 'data.studentId' }
+        ]
+      }
+    }
+  }
+});
+```
+
+## How It Works
+
+### 1️⃣ Event Appended
+You append an event with business data:
+```typescript
+await store.append([{ 
+  type: 'StudentSubscribed', 
+  data: { courseId: 'cs101', studentId: 'alice' } 
+}], result.appendCondition);
+```
+
+### 2️⃣ Keys Extracted
+Your config tells BoundlessDB which fields are consistency keys:
+```typescript
+consistency: {
+  eventTypes: {
+    StudentSubscribed: {
+      keys: [
+        { name: 'course', path: 'data.courseId' },
+        { name: 'student', path: 'data.studentId' }
+      ]
+    }
+  }
+}
+// → Extracts: course='cs101', student='alice'
+```
+
+### 3️⃣ Index Updated
+Keys are stored in a separate index table, linked to the event position:
+```
+event_keys: [pos:1, course, cs101], [pos:1, student, alice]
+```
+
+### 4️⃣ Query by Keys
+Find all events matching any combination of key conditions:
+```typescript
+const result = await store.read({
+  conditions: [
+    { type: 'StudentSubscribed', key: 'course', value: 'cs101' }
+  ]
+});
+// result.appendCondition captures: "I read all matching events up to position X"
+```
+
+## The DCB Pattern: Read → Decide → Write
+
+```typescript
+// 1️⃣ READ — Query events and get an appendCondition
+const { events, appendCondition } = await store.read({
+  conditions: [
+    { type: 'CourseCreated', key: 'course', value: 'cs101' },
+    { type: 'StudentSubscribed', key: 'course', value: 'cs101' },
+  ]
+});
+
+// 2️⃣ DECIDE — Build state, run business logic
+const state = events.reduce(evolve, initialState);
+const newEvents = decide(command, state);
+
+// 3️⃣ WRITE — Append with optimistic concurrency
+const result = await store.append(newEvents, appendCondition);
+```
+
+### Define Your Functions
+
+```typescript
+const initialState = { enrolled: 0, capacity: 30 };
+
+// evolve: (state, event) → new state
+const evolve = (state, event) => {
+  switch (event.type) {
+    case 'StudentSubscribed':
+      return { ...state, enrolled: state.enrolled + 1 };
+    default:
+      return state;
+  }
+};
+
+// decide: (command, state) → events[]
+const decide = (command, state) => {
+  if (state.enrolled >= state.capacity) {
+    throw new Error('Course is full!');
+  }
+  return [{ type: 'StudentSubscribed', data: command }];
+};
+```
+
+### Handle Conflicts
+
+```typescript
+if (result.conflict) {
+  // Someone else wrote while you were deciding
+  console.log('Events since your read:', result.conflictingEvents);
+  // Retry with result.appendCondition
+} else {
+  console.log('Success at position', result.position);
+}
+```
+
+## Fluent Query API
+
+Build queries with a chainable API:
+
+```typescript
+const { events, appendCondition } = await store.query<CourseEvent>()
+  .matchType('CourseCreated')                         // all events of type
+  .matchKey('StudentSubscribed', 'course', 'cs101')   // where key = value
+  .fromPosition(100n)                                 // start from position
+  .limit(50)                                          // limit results
+  .read();
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `matchType(type)` | Match all events of type (unconstrained) |
+| `matchKey(type, key, value)` | Match events where key equals value (constrained) |
+| `fromPosition(bigint)` | Start reading from position |
+| `limit(number)` | Limit number of results |
+| `read()` | Execute query, returns `QueryResult` |
+
+The fluent API is equivalent to calling `store.read()` with conditions — use whichever style you prefer.
+
+## AppendCondition
+
+When you call `read()`, the result contains an `appendCondition` with:
+- The **position** up to which events were read
+- The **query conditions** you used
+
+This is a simple, transparent object — no encoding, no magic:
+
+```typescript
+// Option 1: Use appendCondition from read()
+const result = await store.read({ conditions });
+await store.append(newEvents, result.appendCondition);
+
+// Option 2: Create conditions manually
+await store.append(newEvents, {
+  position: 42n,
+  conditions: [{ type: 'UserCreated', key: 'username', value: 'alice' }]
+});
+
+// Option 3: Skip consistency check entirely
+await store.append(newEvents, null);
+```
+
+This flexibility lets you:
+- **Create uniqueness checks without reading first** (e.g., "username must be unique")
+- **Build custom retry logic** by constructing conditions manually
+- **Optimize performance** by skipping unnecessary reads
+
+## Query Across Multiple Dimensions
+
+Traditional streams give you ONE boundary. DCB lets you query ANY combination:
+
+```typescript
+// "Has Alice already enrolled in CS101?"
+const result = await store.read({
+  conditions: [
+    { type: 'StudentSubscribed', key: 'course', value: 'cs101' },
+    { type: 'StudentSubscribed', key: 'student', value: 'alice' },
+  ]
+});
+// Checks BOTH course AND student boundaries in one query!
+```
+
+## Config-based Key Extraction
+
+Keys are extracted from event payloads via configuration — events stay pure:
+
+```typescript
+const consistency = {
+  eventTypes: {
+    OrderPlaced: {
+      keys: [
+        { name: 'order', path: 'data.orderId' },
+        { name: 'customer', path: 'data.customer.id' },
+        { name: 'month', path: 'data.timestamp', transform: 'MONTH' }
+      ]
+    }
+  }
+};
+```
+
+### Key Options
+
+| Option | Description |
+|--------|-------------|
+| `name` | Key name for queries |
+| `path` | Dot-notation path in event (e.g., `data.customer.id`) |
+| `transform` | Transform the extracted value (see below) |
+| `nullHandling` | `error` (default), `skip`, `default` |
+| `defaultValue` | Value when `nullHandling: 'default'` |
+
+### Transforms
+
+Transforms modify the extracted value before indexing:
+
+| Transform | Input | Output | Use Case |
+|-----------|-------|--------|----------|
+| `LOWER` | `"Alice@Email.COM"` | `"alice@email.com"` | Case-insensitive matching |
+| `UPPER` | `"alice"` | `"ALICE"` | Normalized codes |
+| `MONTH` | `"2026-02-20T14:30:00Z"` | `"2026-02"` | Monthly partitioning |
+| `YEAR` | `"2026-02-20T14:30:00Z"` | `"2026"` | Yearly aggregation |
+| `DATE` | `"2026-02-20T14:30:00Z"` | `"2026-02-20"` | Daily partitioning |
+
+**Example: Time-based partitioning**
+
+```typescript
+const consistency = {
+  eventTypes: {
+    OrderPlaced: {
+      keys: [
+        { name: 'order', path: 'data.orderId' },
+        { name: 'month', path: 'data.placedAt', transform: 'MONTH' }
+      ]
+    }
+  }
+};
+
+// Event: { type: 'OrderPlaced', data: { orderId: 'ORD-123', placedAt: '2026-02-20T14:30:00Z' } }
+// Extracted keys: order="ORD-123", month="2026-02"
+
+// Query all orders from February 2026:
+const { events } = await store.read({
+  conditions: [{ type: 'OrderPlaced', key: 'month', value: '2026-02' }]
+});
+```
+
+This is great for **Close the Books** patterns — query all events in a time period efficiently!
+
+## Auto-Reindex on Config Change
+
+The config is hashed and stored in the database. On startup:
+
+```
+stored_hash:  "a1b2c3..."  (from last run)
+current_hash: "x9y8z7..."  (from your config)
+
+→ Hash mismatch detected!
+→ Rebuilding key index...
+→ ✅ Reindex complete: 1523 events, 4211 keys (847ms)
+```
+
+**Just change your config and restart.** No manual migration needed!
+
+## Browser Usage
+
+BoundlessDB works **entirely in the browser** with no server required:
+
+```html
+<script type="module">
+  import { createEventStore, SqlJsStorage } from './boundless.browser.js';
+
+  const store = createEventStore({
+    storage: new SqlJsStorage(),
+    consistency: {
+      eventTypes: {
+        TodoAdded: { keys: [{ name: 'list', path: 'data.listId' }] }
+      }
+    }
+  });
+
+  // Everything runs client-side!
+</script>
+```
+
+### Build Browser Bundle
+
+```bash
+npm run build:browser
+# → ui/public/boundless.browser.js (~100KB)
+```
+
+## Storage Backends
+
+| Backend | Environment | Persistence |
+|---------|-------------|-------------|
+| `SqliteStorage` | Node.js | File or `:memory:` |
+| `SqlJsStorage` | Browser | In-memory (WASM) |
+| `PostgresStorage` | Node.js | PostgreSQL database |
+| `InMemoryStorage` | Any | None (testing) |
+
+### PostgreSQL Storage
+
+For production deployments with PostgreSQL:
+
+```typescript
+import { createEventStore, PostgresStorage } from 'boundlessdb';
+
+const storage = new PostgresStorage('postgresql://user:pass@localhost/mydb');
+await storage.init();  // Required: creates tables if they don't exist
+
+const store = createEventStore({
+  storage,
+  consistency: { /* ... */ }
+});
+```
+
+**Note:** PostgreSQL support requires the `pg` package:
+
+```bash
+npm install pg
+```
+
+## Typed Events
+
+Define type-safe events using the `Event` marker type:
+
+```typescript
+import { Event, EventStore } from 'boundlessdb';
+
+// Define your events
+type ProductItemAdded = Event<'ProductItemAdded', {
+  cartId: string;
+  productId: string;
+  quantity: number;
+}>;
+
+type ProductItemRemoved = Event<'ProductItemRemoved', {
+  cartId: string;
+  productId: string;
+}>;
+
+// Create a union type for all cart events
+type CartEvents = ProductItemAdded | ProductItemRemoved;
+
+// Read with type safety
+const result = await store.read<CartEvents>({
+  conditions: [{ type: 'ProductItemAdded', key: 'cart', value: 'cart-123' }]
+});
+
+// TypeScript knows the event types!
+for (const event of result.events) {
+  if (event.type === 'ProductItemAdded') {
+    console.log(event.data.quantity);  // ✅ typed as number
+  }
+}
+```
+
+## Query Conditions
+
+Query conditions support both **constrained** (with key/value) and **unconstrained** (type-only) queries.
+
+### Constrained Query
+Match events of a type where a specific key has a specific value:
+
+```typescript
+// Get ProductItemAdded events where cart='cart-123'
+const result = await store.read({
+  conditions: [
+    { type: 'ProductItemAdded', key: 'cart', value: 'cart-123' }
+  ]
+});
+```
+
+### Unconstrained Query
+Omit `key` and `value` to match **all events of a type**:
+
+```typescript
+// Get ALL ProductItemAdded events (regardless of cart)
+const result = await store.read({
+  conditions: [
+    { type: 'ProductItemAdded' }  // no key/value = match all
+  ]
+});
+```
+
+### Mixed Conditions
+Combine constrained and unconstrained in one query (OR logic):
+
+```typescript
+// "Give me the course definition + all enrollments for cs101"
+const result = await store.read({
+  conditions: [
+    { type: 'CourseCreated', key: 'course', value: 'cs101' },
+    { type: 'StudentSubscribed', key: 'course', value: 'cs101' },
+    { type: 'StudentUnsubscribed', key: 'course', value: 'cs101' },
+  ]
+});
+
+// "All courses + only Alice's enrollments"
+const result = await store.read({
+  conditions: [
+    { type: 'CourseCreated' },                                  // unconstrained: ALL courses
+    { type: 'StudentSubscribed', key: 'student', value: 'alice' } // constrained: only Alice
+  ]
+});
+```
+
+### Same Type, Multiple Values
+Query multiple values of the same key:
+
+```typescript
+// Get ProductItemAdded for cart-1 OR cart-2
+const result = await store.read({
+  conditions: [
+    { type: 'ProductItemAdded', key: 'cart', value: 'cart-1' },
+    { type: 'ProductItemAdded', key: 'cart', value: 'cart-2' }
+  ]
+});
+```
+
+### Type Safety
+With TypeScript, conditions are type-safe — you must provide either:
+- **Only `type`** (unconstrained), or
+- **`type` + `key` + `value`** (constrained)
+
+```typescript
+// ✅ Valid
+{ type: 'ProductItemAdded' }
+{ type: 'ProductItemAdded', key: 'cart', value: 'cart-123' }
+
+// ❌ TypeScript Error — key without value not allowed
+{ type: 'ProductItemAdded', key: 'cart' }
+```
+
+### Empty Conditions
+Empty conditions returns **all events** in the store:
+
+```typescript
+// Get ALL events (useful for admin/debug/export)
+const result = await store.read({ conditions: [] });
+```
+
+## API Reference
+
+### `createEventStore(options)`
+
+```typescript
+const store = createEventStore({
+  storage: SqliteStorage | SqlJsStorage | PostgresStorage | InMemoryStorage,
+  consistency: ConsistencyConfig,  // Key extraction rules
+});
+```
+
+### `store.read<E>(query)`
+
+```typescript
+const result = await store.read<CartEvents>({
+  conditions: [{ type, key?, value? }],
+  fromPosition?: bigint,
+  limit?: number,
+});
+
+result.events           // StoredEvent<E>[]
+result.position         // bigint
+result.conditions       // QueryCondition[]
+result.appendCondition  // AppendCondition (for store.append)
+result.count            // number
+result.isEmpty()        // boolean
+result.first()          // StoredEvent<E> | undefined
+result.last()           // StoredEvent<E> | undefined
+```
+
+### `store.append<E>(events, condition)`
+
+```typescript
+// With appendCondition from read()
+const readResult = await store.read<CartEvents>({ conditions });
+const result = await store.append<CartEvents>([newEvent], readResult.appendCondition);
+
+// With manual AppendCondition
+const result = await store.append<CartEvents>([newEvent], {
+  position: 42n,
+  conditions: [{ type: 'UserCreated', key: 'username', value: 'alice' }]
+});
+
+// Without consistency check
+const result = await store.append<CartEvents>([newEvent], null);
+
+// Result handling
+if (result.conflict) {
+  result.conflictingEvents;  // StoredEvent<E>[] - what changed since your read
+  result.appendCondition;    // Fresh condition for retry
+} else {
+  result.position;           // Position of last appended event
+  result.appendCondition;    // Condition for next operation
+}
+```
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run build:browser
+```
+
+## Related
+
+- [dcb.events](https://dcb.events) — Dynamic Consistency Boundaries
+- [Giraflow](https://giraflow.dev) — Event Modeling visualization
+
+---
+
+Built with ❤️ for [Event Sourcing](https://www.eventstore.com/event-sourcing)

package/dist/better-sqlite3-shim.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser shim for better-sqlite3
+ *
+ * This module throws a helpful error if someone tries to use SqliteStorage in the browser.
+ * Use SqlJsStorage instead for browser environments.
+ */
+declare class BrowserNotSupportedError extends Error {
+    constructor();
+}
+export default function Database(_path?: string): void;
+export { BrowserNotSupportedError };
+//# sourceMappingURL=better-sqlite3-shim.d.ts.map

package/dist/better-sqlite3-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-sqlite3-shim.d.ts","sourceRoot":"","sources":["../src/better-sqlite3-shim.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAM,wBAAyB,SAAQ,KAAK;;CAQ3C;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,QAE9C;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/better-sqlite3-shim.js

@@ -0,0 +1,18 @@
+/**
+ * Browser shim for better-sqlite3
+ *
+ * This module throws a helpful error if someone tries to use SqliteStorage in the browser.
+ * Use SqlJsStorage instead for browser environments.
+ */
+class BrowserNotSupportedError extends Error {
+    constructor() {
+        super('better-sqlite3 is not available in browser environments. ' +
+            'Use SqlJsStorage instead for browser-based event storage.');
+        this.name = 'BrowserNotSupportedError';
+    }
+}
+export default function Database(_path) {
+    throw new BrowserNotSupportedError();
+}
+export { BrowserNotSupportedError };
+//# sourceMappingURL=better-sqlite3-shim.js.map

package/dist/better-sqlite3-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-sqlite3-shim.js","sourceRoot":"","sources":["../src/better-sqlite3-shim.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,wBAAyB,SAAQ,KAAK;IAC1C;QACE,KAAK,CACH,2DAA2D;YAC3D,2DAA2D,CAC5D,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,KAAc;IAC7C,MAAM,IAAI,wBAAwB,EAAE,CAAC;AACvC,CAAC;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}