@livestore/livestore 0.4.0-dev.17 → 0.4.0-dev.19

package/docs/api/livestore/variables/deepEqual/index.md

@@ -0,0 +1,25 @@
+# deepEqual
+
+> `const` **deepEqual**: \<`T`\>(`a`, `b`) => `boolean`
+
+Defined in: submodules/livestore/packages/@livestore/utils/dist/fast-deep-equal.d.ts:1
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### a
+
+`T`
+
+### b
+
+`T`
+
+## Returns
+
+`boolean`

package/docs/api/livestore/variables/defineEvent/index.md

@@ -0,0 +1,49 @@
+# defineEvent
+
+> `const` **defineEvent**: \<`TName`, `TType`, `TEncoded`, `TDerived`\>(`args`) => [`EventDef`](/api/livestore/type-aliases/eventdef/)\<`TName`, `TType`, `TEncoded`, `TDerived`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/EventDef/define.d.ts:80
+
+Creates an event definition with full control over all options.
+
+This is the low-level function for creating events. For most cases,
+prefer using `synced()` or `clientOnly()` which provide simpler APIs.
+
+## Type Parameters
+
+### TName
+
+`TName` *extends* `string`
+
+### TType
+
+`TType`
+
+### TEncoded
+
+`TEncoded` = `TType`
+
+### TDerived
+
+`TDerived` *extends* `boolean` = `false`
+
+## Parameters
+
+### args
+
+`object` & [`DefineEventOptions`](/api/livestore/type-aliases/defineeventoptions/)\<`TType`, `TDerived`\>
+
+## Returns
+
+[`EventDef`](/api/livestore/type-aliases/eventdef/)\<`TName`, `TType`, `TEncoded`, `TDerived`\>
+
+## Example
+
+```ts
+const customEvent = defineEvent({
+  name: 'v1.CustomEvent',
+  schema: Schema.Struct({ data: Schema.String }),
+  clientOnly: false,
+  derived: false,
+})
+```

package/docs/api/livestore/variables/defineFacts/index.md

@@ -0,0 +1,42 @@
+# defineFacts
+
+> `const` **defineFacts**: \<`TRecord`\>(`record`) => `TRecord`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/EventDef/facts.d.ts:117
+
+Helper to define a typed record of fact constructors.
+Returns the input unchanged but provides type inference.
+
+## Type Parameters
+
+### TRecord
+
+`TRecord` *extends* `Record`\<`string`, [`EventDefFactInput`](/api/livestore/type-aliases/eventdeffactinput/) \| (...`args`) => [`EventDefFactInput`](/api/livestore/type-aliases/eventdeffactinput/)\>
+
+## Parameters
+
+### record
+
+`TRecord`
+
+## Returns
+
+`TRecord`
+
+## Example
+
+```ts
+const facts = defineFacts({
+  // Simple fact (value = true)
+  initialized: 'system:initialized',
+
+  // Parameterized fact constructor
+  todoExists: (id: string) => [`todo:${id}`, true] as const,
+
+  // Fact with complex value
+  todoStatus: (id: string, status: string) => [`todo:${id}:status`, status] as const,
+})
+
+// Usage
+facts.todoExists('abc')  // => ['todo:abc', true]
+```

package/docs/api/livestore/variables/defineMaterializer/index.md

@@ -0,0 +1,39 @@
+# defineMaterializer
+
+> `const` **defineMaterializer**: \<`TEventDef`\>(`_eventDef`, `materializer`) => [`Materializer`](/api/livestore/type-aliases/materializer/)\<`TEventDef`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/EventDef/materializer.d.ts:111
+
+Type-safe wrapper for defining a single materializer.
+
+Useful when defining materializers separately from the `materializers()` builder.
+The first argument provides type inference for the second.
+
+## Type Parameters
+
+### TEventDef
+
+`TEventDef` *extends* [`AnyWithoutFn`](/api/livestore/livestore/namespaces/eventdef/type-aliases/anywithoutfn/)
+
+## Parameters
+
+### \_eventDef
+
+`TEventDef`
+
+### materializer
+
+[`Materializer`](/api/livestore/type-aliases/materializer/)\<`TEventDef`\>
+
+## Returns
+
+[`Materializer`](/api/livestore/type-aliases/materializer/)\<`TEventDef`\>
+
+## Example
+
+```ts
+const todoCreatedHandler = defineMaterializer(
+  events.todoCreated,
+  ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+)
+```

package/docs/api/livestore/variables/getDefaultValuesDecoded/index.md

@@ -0,0 +1,25 @@
+# getDefaultValuesDecoded
+
+> `const` **getDefaultValuesDecoded**: \<`TTableDef`\>(`tableDef`, `fallbackValues?`) => `Record`\<`string`, `any`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/state/sqlite/schema-helpers.d.ts:3
+
+## Type Parameters
+
+### TTableDef
+
+`TTableDef` *extends* [`TableDefBase`](/api/livestore/livestore/namespaces/state/namespaces/sqlite/type-aliases/tabledefbase/)
+
+## Parameters
+
+### tableDef
+
+`TTableDef`
+
+### fallbackValues?
+
+`Record`\<`string`, `any`\>
+
+## Returns
+
+`Record`\<`string`, `any`\>

package/docs/api/livestore/variables/getDefaultValuesEncoded/index.md

@@ -0,0 +1,25 @@
+# getDefaultValuesEncoded
+
+> `const` **getDefaultValuesEncoded**: \<`TTableDef`\>(`tableDef`, `fallbackValues?`) => `Record`\<`string`, `any`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/state/sqlite/schema-helpers.d.ts:2
+
+## Type Parameters
+
+### TTableDef
+
+`TTableDef` *extends* [`TableDefBase`](/api/livestore/livestore/namespaces/state/namespaces/sqlite/type-aliases/tabledefbase/)
+
+## Parameters
+
+### tableDef
+
+`TTableDef`
+
+### fallbackValues?
+
+`Record`\<`string`, `any`\>
+
+## Returns
+
+`Record`\<`string`, `any`\>

package/docs/api/livestore/variables/getEventDef/index.md

@@ -0,0 +1,33 @@
+# getEventDef
+
+> `const` **getEventDef**: \<`TSchema`\>(`schema`, `eventName`) => `object`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/schema.d.ts:63
+
+## Type Parameters
+
+### TSchema
+
+`TSchema` *extends* [`LiveStoreSchema`](/api/livestore/interfaces/livestoreschema/)
+
+## Parameters
+
+### schema
+
+`TSchema`
+
+### eventName
+
+`string`
+
+## Returns
+
+`object`
+
+### eventDef
+
+> **eventDef**: [`AnyWithoutFn`](/api/livestore/livestore/namespaces/eventdef/type-aliases/anywithoutfn/)
+
+### materializer
+
+> **materializer**: [`Materializer`](/api/livestore/type-aliases/materializer/)

package/docs/api/livestore/variables/isLiveStoreSchema/index.md

@@ -0,0 +1,21 @@
+# isLiveStoreSchema
+
+> `const` **isLiveStoreSchema**: (`value`) => `value is LiveStoreSchema<any, any>`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/schema.d.ts:33
+
+Runtime type guard for LiveStoreSchema.
+
+The guard intentionally performs lightweight structural checks that are
+stable across implementations. It verifies the identifying symbol marker
+and the presence of core maps/state used at runtime.
+
+## Parameters
+
+### value
+
+`unknown`
+
+## Returns
+
+`value is LiveStoreSchema<any, any>`

package/docs/api/livestore/variables/liveStoreVersion/index.md

@@ -0,0 +1,5 @@
+# liveStoreVersion
+
+> `const` **liveStoreVersion**: `"0.4.0-dev.18"`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/version.d.ts:1

package/docs/api/livestore/variables/makeSchema/index.md

@@ -0,0 +1,21 @@
+# makeSchema
+
+> `const` **makeSchema**: \<`TInputSchema`\>(`inputSchema`) => [`DeriveSchema`](/api/livestore/livestore/namespaces/frominputschema/type-aliases/deriveschema/)\<`TInputSchema`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/schema.d.ts:60
+
+## Type Parameters
+
+### TInputSchema
+
+`TInputSchema` *extends* [`InputSchema`](/api/livestore/interfaces/inputschema/)
+
+## Parameters
+
+### inputSchema
+
+`TInputSchema`
+
+## Returns
+
+[`DeriveSchema`](/api/livestore/livestore/namespaces/frominputschema/type-aliases/deriveschema/)\<`TInputSchema`\>

package/docs/api/livestore/variables/makeShutdownDeferred/index.md

@@ -0,0 +1,5 @@
+# makeShutdownDeferred
+
+> `const` **makeShutdownDeferred**: `Effect.Effect`\<[`ShutdownDeferred`](/api/livestore/type-aliases/shutdowndeferred/)\>
+
+Defined in: [submodules/livestore/packages/@livestore/livestore/src/store/store-types.ts:48](https://github.com/livestorejs/livestore/blob/e27f6dd63400fece0f2344d09d3e47f57ecc98e7/packages/@livestore/livestore/src/store/store-types.ts#L48)

package/docs/api/livestore/variables/materializers/index.md

@@ -0,0 +1,58 @@
+# materializers
+
+> `const` **materializers**: \<`TInputRecord`\>(`_eventDefRecord`, `handlers`) => `{ [TEventName in TInputRecord[keyof TInputRecord]["name"] as Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>["options"]["derived"] extends true ? never : TEventName]: Materializer<Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>> }`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/EventDef/materializer.d.ts:146
+
+Builder function for creating a type-safe materializer map.
+
+This is the primary way to define materializers in LiveStore. It ensures:
+- Every non-derived event has a corresponding materializer
+- Materializer argument types match their event schemas
+- Derived events are excluded from the required handlers
+
+## Type Parameters
+
+### TInputRecord
+
+`TInputRecord` *extends* `Record`\<`string`, [`AnyWithoutFn`](/api/livestore/livestore/namespaces/eventdef/type-aliases/anywithoutfn/)\>
+
+## Parameters
+
+### \_eventDefRecord
+
+`TInputRecord`
+
+### handlers
+
+`{ [TEventName in TInputRecord[keyof TInputRecord]["name"] as Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>["options"]["derived"] extends true ? never : TEventName]: Materializer<Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>> }`
+
+## Returns
+
+`{ [TEventName in TInputRecord[keyof TInputRecord]["name"] as Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>["options"]["derived"] extends true ? never : TEventName]: Materializer<Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>> }`
+
+## Example
+
+```ts
+
+const handlers = State.SQLite.materializers(events, {
+  // Handler for each event - argument types are inferred
+  'v1.TodoCreated': ({ id, text, completed }) =>
+    tables.todos.insert({ id, text, completed }),
+
+  'v1.TodoUpdated': ({ id, text }) =>
+    tables.todos.update({ text }).where({ id }),
+
+  // Can return multiple operations
+  'v1.UserCreatedWithDefaults': ({ userId, name }) => [
+    tables.users.insert({ id: userId, name }),
+    tables.settings.insert({ userId, theme: 'light' }),
+  ],
+
+  // Can query current state
+  'v1.TodoToggled': ({ id }, { query }) => {
+    const todo = query(tables.todos.select().where({ id }).first())
+    return tables.todos.update({ completed: !todo?.completed }).where({ id })
+  },
+})
+```

package/docs/api/livestore/variables/normalizeUnknownEventHandling/index.md

@@ -0,0 +1,15 @@
+# normalizeUnknownEventHandling
+
+> `const` **normalizeUnknownEventHandling**: (`input`) => [`HandlingConfig`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/handlingconfig/)
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/unknown-events.d.ts:35
+
+## Parameters
+
+### input
+
+[`HandlingConfig`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/handlingconfig/) | `undefined`
+
+## Returns
+
+[`HandlingConfig`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/handlingconfig/)

package/docs/api/livestore/variables/prepareBindValues/index.md

@@ -0,0 +1,26 @@
+# prepareBindValues
+
+> `const` **prepareBindValues**: (`values`, `statement`) => [`PreparedBindValues`](/api/livestore/type-aliases/preparedbindvalues/)
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/util.d.ts:24
+
+Prepare bind values to send to SQLite
+Add $ to the beginning of keys; which we use as our interpolation syntax
+We also strip out any params that aren't used in the statement,
+because rusqlite doesn't allow unused named params
+TODO: Search for unused params via proper parsing, not string search
+TODO: Also make sure that the SQLite binding limit of 1000 is respected
+
+## Parameters
+
+### values
+
+[`Bindable`](/api/livestore/type-aliases/bindable/)
+
+### statement
+
+`string`
+
+## Returns
+
+[`PreparedBindValues`](/api/livestore/type-aliases/preparedbindvalues/)

package/docs/api/livestore/variables/provideOtel/index.md

@@ -0,0 +1,45 @@
+# provideOtel
+
+> `const` **provideOtel**: (`{ otelTracer, parentSpanContext }`) => \<`A`, `E`, `R`\>(`effect`) => `Effect.Effect`\<`A`, `E`, `Exclude`\<`R`, `OtelTracer.OtelTracer`\>\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/otel.d.ts:3
+
+## Parameters
+
+### \{ otelTracer, parentSpanContext \}
+
+#### otelTracer?
+
+`otel.Tracer`
+
+#### parentSpanContext?
+
+`otel.Context`
+
+## Returns
+
+> \<`A`, `E`, `R`\>(`effect`): `Effect.Effect`\<`A`, `E`, `Exclude`\<`R`, `OtelTracer.OtelTracer`\>\>
+
+### Type Parameters
+
+#### A
+
+`A`
+
+#### E
+
+`E`
+
+#### R
+
+`R`
+
+### Parameters
+
+#### effect
+
+`Effect.Effect`\<`A`, `E`, `R`\>
+
+### Returns
+
+`Effect.Effect`\<`A`, `E`, `Exclude`\<`R`, `OtelTracer.OtelTracer`\>\>

package/docs/api/livestore/variables/queryDb/index.md

@@ -0,0 +1,115 @@
+# queryDb
+
+> `const` **queryDb**: \{\<`TResultSchema`, `TResult`\>(`queryInput`, `options?`): [`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>; \<`TResultSchema`, `TResult`\>(`queryInput`, `options?`): [`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>; \}
+
+Defined in: [submodules/livestore/packages/@livestore/livestore/src/live-queries/db-query.ts:75](https://github.com/livestorejs/livestore/blob/e27f6dd63400fece0f2344d09d3e47f57ecc98e7/packages/@livestore/livestore/src/live-queries/db-query.ts#L75)
+
+NOTE `queryDb` is only supposed to read data. Don't use it to insert/update/delete data but use events instead.
+
+When using contextual data when constructing the query, please make sure to include it in the `deps` option.
+
+## Call Signature
+
+> \<`TResultSchema`, `TResult`\>(`queryInput`, `options?`): [`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>
+
+### Type Parameters
+
+#### TResultSchema
+
+`TResultSchema`
+
+#### TResult
+
+`TResult` = `TResultSchema`
+
+### Parameters
+
+#### queryInput
+
+`QueryInputRaw`\<`TResultSchema`, readonly `any`[]\> | [`QueryBuilder`](/api/livestore/type-aliases/querybuilder/)\<`TResultSchema`, `any`, `any`\>
+
+#### options?
+
+##### deps?
+
+`DepKey`
+
+##### label?
+
+`string`
+
+Used for debugging / devtools
+
+##### map?
+
+(`rows`) => `TResult`
+
+### Returns
+
+[`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>
+
+## Call Signature
+
+> \<`TResultSchema`, `TResult`\>(`queryInput`, `options?`): [`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>
+
+### Type Parameters
+
+#### TResultSchema
+
+`TResultSchema`
+
+#### TResult
+
+`TResult` = `TResultSchema`
+
+### Parameters
+
+#### queryInput
+
+(`get`) => `QueryInputRaw`\<`TResultSchema`, readonly `any`[]\> | (`get`) => [`QueryBuilder`](/api/livestore/type-aliases/querybuilder/)\<`TResultSchema`, `any`, `any`\>
+
+#### options?
+
+##### deps?
+
+`DepKey`
+
+##### label?
+
+`string`
+
+Used for debugging / devtools
+
+##### map?
+
+(`rows`) => `TResult`
+
+### Returns
+
+[`LiveQueryDef`](/api/livestore/interfaces/livequerydef/)\<`TResult`\>
+
+## Examples
+
+```ts
+const todos$ = queryDb(tables.todos.where({ complete: true }))
+```
+
+```ts
+// Group-by raw SQL query
+const colorCounts$ = queryDb({
+  query: sql`SELECT color, COUNT(*) as count FROM todos WHERE complete = ? GROUP BY color`,
+  schema: Schema.Array(Schema.Struct({
+    color: Schema.String,
+    count: Schema.Number,
+  })),
+  bindValues: [1],
+})
+```
+
+```ts
+// Using contextual data when constructing the query
+const makeFilteredQuery = (filter: string) =>
+  queryDb(tables.todos.where({ title: { op: 'like', value: filter } }), { deps: [filter] })
+
+const filteredTodos$ = makeFilteredQuery('buy coffee')
+```

package/docs/api/livestore/variables/resolveEventDef/index.md

@@ -0,0 +1,28 @@
+# resolveEventDef
+
+> `const` **resolveEventDef**: (`schema`, `context`) => `Effect.Effect`\<[`Resolved`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/resolved/), `UnknownEventError`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/unknown-events.d.ts:46
+
+Resolves the runtime event definition + materializer for a given event name.
+
+Behaviour is intentionally split across the result and error channels:
+- For `'fail'` handling, we surface an `UnknownEventError` via the failure channel so
+  callers can convert it into the appropriate domain error (for example `MaterializeError`).
+- For all other strategies (`warn`, `ignore`, `callback`) we succeed with an
+  `{ _tag: 'unknown' }` value, signalling that the caller should skip the event while
+  continuing normal processing.
+
+## Parameters
+
+### schema
+
+[`LiveStoreSchema`](/api/livestore/interfaces/livestoreschema/)
+
+### context
+
+[`ResolveContext`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/resolvecontext/)
+
+## Returns
+
+`Effect.Effect`\<[`Resolved`](/api/livestore/livestore/namespaces/unknownevents/type-aliases/resolved/), `UnknownEventError`\>

package/docs/api/livestore/variables/sql/index.md

@@ -0,0 +1,24 @@
+# sql
+
+> `const` **sql**: (`template`, ...`args`) => `string`
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/util.d.ts:15
+
+This is a tag function for tagged literals.
+it lets us get syntax highlighting on SQL queries in VSCode, but
+doesn't do anything at runtime.
+Code copied from: https://esdiscuss.org/topic/string-identity-template-tag
+
+## Parameters
+
+### template
+
+`TemplateStringsArray`
+
+### args
+
+...`unknown`[]
+
+## Returns
+
+`string`

package/docs/api/livestore/variables/synced/index.md

@@ -0,0 +1,55 @@
+# synced
+
+> `const` **synced**: \<`TName`, `TType`, `TEncoded`\>(`args`) => [`EventDef`](/api/livestore/type-aliases/eventdef/)\<`TName`, `TType`, `TEncoded`\>
+
+Defined in: submodules/livestore/packages/@livestore/common/dist/schema/EventDef/define.d.ts:112
+
+Creates a synced event definition.
+
+Synced events are sent to the sync backend and distributed to all connected
+clients. Use this for collaborative data that should be shared across users
+and devices.
+
+Event names should be versioned (e.g., `v1.TodoCreated`) to support
+schema evolution over time.
+
+## Type Parameters
+
+### TName
+
+`TName` *extends* `string`
+
+### TType
+
+`TType`
+
+### TEncoded
+
+`TEncoded` = `TType`
+
+## Parameters
+
+### args
+
+`object` & `Omit`\<[`DefineEventOptions`](/api/livestore/type-aliases/defineeventoptions/)\<`TType`, `false`\>, `"derived"` \| `"clientOnly"`\>
+
+## Returns
+
+[`EventDef`](/api/livestore/type-aliases/eventdef/)\<`TName`, `TType`, `TEncoded`\>
+
+## Example
+
+```ts
+
+const todoCreated = Events.synced({
+  name: 'v1.TodoCreated',
+  schema: Schema.Struct({
+    id: Schema.String,
+    text: Schema.String,
+    completed: Schema.Boolean,
+  }),
+})
+
+// Commit the event
+store.commit(todoCreated({ id: 'abc', text: 'Buy milk', completed: false }))
+```