@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

package/dist/schema/EventDef/event-def.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-def.js.map

package/dist/schema/EventDef/event-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-def.js","sourceRoot":"","sources":["../../../src/schema/EventDef/event-def.ts"],"names":[],"mappings":""}

package/dist/schema/EventDef/facts.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Facts System for Event Constraints (Experimental)
+ *
+ * The facts system enables defining constraints and dependencies between events.
+ * Facts are key-value pairs that events can read, set, or require, allowing
+ * LiveStore to understand event relationships for:
+ * - History constraints (ordering requirements)
+ * - Event compaction (which events can be safely merged)
+ * - Conflict detection during sync
+ *
+ * @experimental This system is not fully implemented yet.
+ *
+ * @example
+ * ```ts
+ * const facts = defineFacts({
+ *   todoExists: (id: string) => [`todo:${id}`, true],
+ *   userOwns: (userId: string, todoId: string) => [`owns:${userId}:${todoId}`, true],
+ * })
+ *
+ * const todoCreated = Events.synced({
+ *   name: 'v1.TodoCreated',
+ *   schema: Schema.Struct({ id: Schema.String, userId: Schema.String }),
+ *   facts: ({ id, userId }) => ({
+ *     modify: { set: [facts.todoExists(id), facts.userOwns(userId, id)] },
+ *     require: [],
+ *   }),
+ * })
+ * ```
+ * @module
+ */
+/** String key identifying a fact (e.g., `"todo:abc123"` or `"user:owner:xyz"`). */
+export type EventDefKey = string;
+/** String identifier for a fact type. */
+export type EventDefFact = string;
+/** Immutable map of fact keys to their current values. */
+export type EventDefFacts = ReadonlyMap<string, any>;
+/**
+ * Groups of facts that an event interacts with.
+ * Used internally to track how events modify and depend on facts.
+ */
+export type EventDefFactsGroup = {
+    /** Facts this event sets to a new value. */
+    modifySet: EventDefFacts;
+    /** Facts this event removes/unsets. */
+    modifyUnset: EventDefFacts;
+    /**
+     * Facts this event requires to exist with specific values.
+     * Events on independent dependency branches are commutative,
+     * which can facilitate more prioritized syncing.
+     */
+    depRequire: EventDefFacts;
+    /** Facts this event reads (but doesn't require). */
+    depRead: EventDefFacts;
+};
+/** Mutable snapshot of facts state at a point in time. */
+export type EventDefFactsSnapshot = Map<string, any>;
+/**
+ * Input format for specifying a fact.
+ * Either a simple key string (value defaults to `true`) or a `[key, value]` tuple.
+ *
+ * @example
+ * ```ts
+ * // Simple key (value = true)
+ * const fact1: EventDefFactInput = 'todo:abc123'
+ *
+ * // Key-value tuple
+ * const fact2: EventDefFactInput = ['todo:abc123', { status: 'active' }]
+ * ```
+ */
+export type EventDefFactInput = string | readonly [string, any];
+/**
+ * Callback function that defines how an event interacts with the facts system.
+ * Called during event processing to determine fact constraints.
+ *
+ * @example
+ * ```ts
+ * const factsCallback: FactsCallback<{ id: string }> = (args, currentFacts) => ({
+ *   modify: {
+ *     set: [`item:${args.id}`],  // Create/update this fact
+ *     unset: [],                  // No facts to remove
+ *   },
+ *   require: currentFacts.has('initialized') ? [] : ['initialized'],
+ * })
+ * ```
+ */
+export type FactsCallback<TTo> = (args: TTo, currentFacts: EventDefFacts) => {
+    modify: {
+        /** Facts to set (create or update). */
+        set: Iterable<EventDefFactInput>;
+        /** Facts to unset (remove). */
+        unset: Iterable<EventDefFactInput>;
+    };
+    /** Facts that must exist with specific values for this event to be valid. */
+    require: Iterable<EventDefFactInput>;
+};
+/**
+ * Helper to define a typed record of fact constructors.
+ * Returns the input unchanged but provides type inference.
+ *
+ * @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]
+ * ```
+ */
+export declare const defineFacts: <TRecord extends Record<string, EventDefFactInput | ((...args: any[]) => EventDefFactInput)>>(record: TRecord) => TRecord;
+//# sourceMappingURL=facts.d.ts.map

package/dist/schema/EventDef/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEpD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,4CAA4C;IAC5C,SAAS,EAAE,aAAa,CAAA;IAExB,uCAAuC;IACvC,WAAW,EAAE,aAAa,CAAA;IAE1B;;;;OAIG;IACH,UAAU,EAAE,aAAa,CAAA;IAEzB,oDAAoD;IACpD,OAAO,EAAE,aAAa,CAAA;CACvB,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,CAC/B,IAAI,EAAE,GAAG,EACT,YAAY,EAAE,aAAa,KACxB;IACH,MAAM,EAAE;QACN,uCAAuC;QACvC,GAAG,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;QAChC,+BAA+B;QAC/B,KAAK,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;KACnC,CAAA;IACD,6EAA6E;IAC7E,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;CACrC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,iBAAiB,CAAC,CAAC,EAE3F,QAAQ,OAAO,KACd,OAAiB,CAAA"}

package/dist/schema/EventDef/facts.js

@@ -0,0 +1,53 @@
+/**
+ * Facts System for Event Constraints (Experimental)
+ *
+ * The facts system enables defining constraints and dependencies between events.
+ * Facts are key-value pairs that events can read, set, or require, allowing
+ * LiveStore to understand event relationships for:
+ * - History constraints (ordering requirements)
+ * - Event compaction (which events can be safely merged)
+ * - Conflict detection during sync
+ *
+ * @experimental This system is not fully implemented yet.
+ *
+ * @example
+ * ```ts
+ * const facts = defineFacts({
+ *   todoExists: (id: string) => [`todo:${id}`, true],
+ *   userOwns: (userId: string, todoId: string) => [`owns:${userId}:${todoId}`, true],
+ * })
+ *
+ * const todoCreated = Events.synced({
+ *   name: 'v1.TodoCreated',
+ *   schema: Schema.Struct({ id: Schema.String, userId: Schema.String }),
+ *   facts: ({ id, userId }) => ({
+ *     modify: { set: [facts.todoExists(id), facts.userOwns(userId, id)] },
+ *     require: [],
+ *   }),
+ * })
+ * ```
+ * @module
+ */
+/**
+ * Helper to define a typed record of fact constructors.
+ * Returns the input unchanged but provides type inference.
+ *
+ * @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]
+ * ```
+ */
+export const defineFacts = (record) => record;
+//# sourceMappingURL=facts.js.map

package/dist/schema/EventDef/facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.js","sourceRoot":"","sources":["../../../src/schema/EventDef/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgFH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAGzB,MAAe,EACN,EAAE,CAAC,MAAM,CAAA"}

package/dist/schema/EventDef/materializer.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Materializer System
+ *
+ * Materializers transform events into SQL mutations (INSERT, UPDATE, DELETE).
+ * Every non-derived event must have a corresponding materializer that defines
+ * how it affects the SQLite database state.
+ *
+ * Materializers are pure functions that receive the event arguments and return
+ * SQL operations. They can also query current state when needed for complex
+ * transformations.
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * const materializers = State.SQLite.materializers(events, {
+ *   'v1.TodoCreated': ({ id, text }) =>
+ *     tables.todos.insert({ id, text, completed: false }),
+ *
+ *   'v1.TodoCompleted': ({ id }) =>
+ *     tables.todos.update({ completed: true }).where({ id }),
+ *
+ *   'v1.TodoDeleted': ({ id, deletedAt }) =>
+ *     tables.todos.update({ deletedAt }).where({ id }),
+ * })
+ * ```
+ * @module
+ */
+import type { SingleOrReadonlyArray } from '@livestore/utils';
+import type { BindValues } from '../../sql-queries/sql-queries.ts';
+import type { ParamsObject } from '../../util.ts';
+import type * as LiveStoreEvent from '../LiveStoreEvent/mod.ts';
+import type { QueryBuilder } from '../state/sqlite/query-builder/mod.ts';
+import type { EventDef } from './event-def.ts';
+import type { EventDefFacts } from './facts.ts';
+/**
+ * Result type for materializer functions.
+ *
+ * Can be one of:
+ * - A QueryBuilder operation (recommended for type safety)
+ * - A raw SQL string
+ * - An object with SQL, bind values, and optional write table tracking
+ */
+export type MaterializerResult = {
+    sql: string;
+    bindValues: BindValues;
+    writeTables?: ReadonlySet<string>;
+} | QueryBuilder.Any | string;
+/**
+ * Function signature for querying current state within a materializer.
+ *
+ * Allows materializers to read existing data when computing mutations.
+ * Can be called with either raw SQL or a type-safe QueryBuilder.
+ *
+ * @example
+ * ```ts
+ * 'v1.TodoUpdated': ({ id, text }, { query }) => {
+ *   const existing = query(tables.todos.select().where({ id }).first())
+ *   if (!existing) return []  // No-op if todo doesn't exist
+ *   return tables.todos.update({ text }).where({ id })
+ * }
+ * ```
+ */
+export type MaterializerContextQuery = {
+    /** Query with raw SQL and bind values. */
+    (args: {
+        query: string;
+        bindValues: ParamsObject;
+    }): ReadonlyArray<unknown>;
+    /** Query with a type-safe QueryBuilder. */
+    <TResult>(qb: QueryBuilder<TResult, any, any>): TResult;
+};
+/**
+ * Function type for transforming an event into database mutations.
+ *
+ * Materializers are the bridge between events and SQLite state. They receive
+ * the decoded event arguments and return SQL operations to execute.
+ *
+ * @example
+ * ```ts
+ * const todoCreatedMaterializer: Materializer<typeof todoCreated> =
+ *   ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+ * ```
+ */
+export type Materializer<TEventDef extends EventDef.AnyWithoutFn = EventDef.AnyWithoutFn> = (
+/** Decoded event arguments. */
+event: TEventDef['schema']['Type'], context: {
+    /** Current facts state (experimental). */
+    currentFacts: EventDefFacts;
+    /** The event definition being materialized. */
+    eventDef: TEventDef;
+    /** Function to query current database state. */
+    query: MaterializerContextQuery;
+    /** Full event metadata including clientId, sessionId, sequence numbers. */
+    event: LiveStoreEvent.Client.Decoded;
+}) => SingleOrReadonlyArray<MaterializerResult>;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const todoCreatedHandler = defineMaterializer(
+ *   events.todoCreated,
+ *   ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+ * )
+ * ```
+ */
+export declare const defineMaterializer: <TEventDef extends EventDef.AnyWithoutFn>(_eventDef: TEventDef, materializer: Materializer<TEventDef>) => Materializer<TEventDef>;
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * 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 })
+ *   },
+ * })
+ * ```
+ */
+export declare const materializers: <TInputRecord extends Record<string, EventDef.AnyWithoutFn>>(_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;
+}>>; }) => { [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;
+}>>; };
+//# sourceMappingURL=materializer.d.ts.map

package/dist/schema/EventDef/materializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializer.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/materializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,KAAK,cAAc,MAAM,0BAA0B,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAClC,GACD,YAAY,CAAC,GAAG,GAChB,MAAM,CAAA;AAEV;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,0CAA0C;IAC1C,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,YAAY,CAAA;KAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAA;IAC3E,2CAA2C;IAC3C,CAAC,OAAO,EAAE,EAAE,EAAE,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAA;CACxD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,QAAQ,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,IAAI;AAC1F,+BAA+B;AAC/B,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAClC,OAAO,EAAE;IACP,0CAA0C;IAC1C,YAAY,EAAE,aAAa,CAAA;IAC3B,+CAA+C;IAC/C,QAAQ,EAAE,SAAS,CAAA;IACnB,gDAAgD;IAChD,KAAK,EAAE,wBAAwB,CAAA;IAC/B,2EAA2E;IAC3E,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO,CAAA;CACrC,KACE,qBAAqB,CAAC,kBAAkB,CAAC,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,SAAS,QAAQ,CAAC,YAAY,EACxE,WAAW,SAAS,EACpB,cAAc,YAAY,CAAC,SAAS,CAAC,KACpC,YAAY,CAAC,SAAS,CAExB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,GAAI,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EACtF,iBAAiB,YAAY,EAC7B,UAAU,GACP,UAAU,IAAI,YAAY,CAAC,MAAM,YAAY,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAChE,YAAY,CAAC,MAAM,YAAY,CAAC,EAChC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CACrB,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,SAAS,IAAI,GAChC,KAAK,GACL,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,YAAY,CAAC,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC,GAC/F,QANE,UAAU;UAED,UAAU;;UAG4D,UAAU;MAI7F,CAAA"}

package/dist/schema/EventDef/materializer.js

@@ -0,0 +1,83 @@
+/**
+ * Materializer System
+ *
+ * Materializers transform events into SQL mutations (INSERT, UPDATE, DELETE).
+ * Every non-derived event must have a corresponding materializer that defines
+ * how it affects the SQLite database state.
+ *
+ * Materializers are pure functions that receive the event arguments and return
+ * SQL operations. They can also query current state when needed for complex
+ * transformations.
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * const materializers = State.SQLite.materializers(events, {
+ *   'v1.TodoCreated': ({ id, text }) =>
+ *     tables.todos.insert({ id, text, completed: false }),
+ *
+ *   'v1.TodoCompleted': ({ id }) =>
+ *     tables.todos.update({ completed: true }).where({ id }),
+ *
+ *   'v1.TodoDeleted': ({ id, deletedAt }) =>
+ *     tables.todos.update({ deletedAt }).where({ id }),
+ * })
+ * ```
+ * @module
+ */
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const todoCreatedHandler = defineMaterializer(
+ *   events.todoCreated,
+ *   ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+ * )
+ * ```
+ */
+export const defineMaterializer = (_eventDef, materializer) => {
+    return materializer;
+};
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * 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 })
+ *   },
+ * })
+ * ```
+ */
+export const materializers = (_eventDefRecord, handlers) => {
+    return handlers;
+};
+//# sourceMappingURL=materializer.js.map

package/dist/schema/EventDef/materializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializer.js","sourceRoot":"","sources":["../../../src/schema/EventDef/materializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA6EH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,SAAoB,EACpB,YAAqC,EACZ,EAAE;IAC3B,OAAO,YAAY,CAAA;AACrB,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,eAA6B,EAC7B,QAOC,EACD,EAAE;IACF,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/dist/schema/EventDef/mod.d.ts

@@ -0,0 +1,6 @@
+export * from './define.ts';
+export * from './deprecated.ts';
+export * from './event-def.ts';
+export * from './facts.ts';
+export * from './materializer.ts';
+//# sourceMappingURL=mod.d.ts.map

package/dist/schema/EventDef/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/mod.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA"}

package/dist/schema/EventDef/mod.js

@@ -0,0 +1,6 @@
+export * from "./define.js";
+export * from "./deprecated.js";
+export * from "./event-def.js";
+export * from "./facts.js";
+export * from "./materializer.js";
+//# sourceMappingURL=mod.js.map

package/dist/schema/EventDef/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/schema/EventDef/mod.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA"}

package/dist/schema/EventSequenceNumber/client.d.ts

@@ -0,0 +1,136 @@
+import { Brand, Schema as S } from '@livestore/utils/effect';
+import { type Type as Global } from './global.ts';
+/** Branded integer type for client-local sequence numbers. */
+export type Type = Brand.Branded<number, 'ClientEventSequenceNumber'>;
+/** Effect Schema for encoding/decoding client sequence numbers. */
+export declare const Schema: S.brand<S.Int, "ClientEventSequenceNumber">;
+/**
+ * Creates a branded client sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ * ```
+ */
+export declare const make: Brand.Constructor<Type>;
+/**
+ * Default client sequence number (0). Used for confirmed/synced events.
+ *
+ * @example
+ * ```ts
+ * const defaultSeq = EventSequenceNumber.Client.DEFAULT // 0
+ * ```
+ */
+export declare const DEFAULT: Type;
+/** Default rebase generation (0). Increments each time the client rebases unconfirmed events. */
+export declare const REBASE_GENERATION_DEFAULT = 0;
+/**
+ * Composite event sequence number consisting of global + client + rebaseGeneration.
+ * Used for client-side event tracking with support for unconfirmed local events.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ */
+export type Composite = {
+    global: Global;
+    client: Type;
+    /**
+     * Generation integer that is incremented whenever the client rebased.
+     * Remains constant for all subsequent events until another rebase occurs.
+     */
+    rebaseGeneration: number;
+};
+/** Input type for creating a Composite sequence number. Allows omitting rebaseGeneration (defaults to 0). */
+export type CompositeInput = Composite | (Omit<typeof CompositeSchema.Encoded, 'rebaseGeneration'> & {
+    rebaseGeneration?: number;
+});
+/** A pair of sequence numbers representing an event and its parent. */
+export type CompositePair = {
+    seqNum: Composite;
+    parentSeqNum: Composite;
+};
+/**
+ * Compare two composite sequence numbers.
+ * Comparison hierarchy: global > client > rebaseGeneration
+ */
+export declare const compare: (a: Composite, b: Composite) => number;
+/**
+ * Convert a composite sequence number to a string representation.
+ *
+ * For notation documentation, see: contributor-docs/events-notation.md
+ */
+export declare const toString: (seqNum: Composite) => string;
+/**
+ * Convert a string representation of a sequence number to a Composite.
+ * Parses strings in the format: e{global}[.{client}][r{rebaseGeneration}]
+ * Examples: "e0", "e0r1", "e0.1", "e0.1r1"
+ *
+ * For full notation documentation, see: contributor-docs/events-notation.md
+ */
+export declare const fromString: (str: string) => Composite;
+/** Creates a Composite sequence number from a global sequence number (client=0, rebaseGeneration=0). */
+export declare const fromGlobal: (seqNum: Global) => Composite;
+/** Returns true if two Composite sequence numbers are structurally equal. */
+export declare const isEqual: (a: Composite, b: Composite) => boolean;
+/** Returns true if `a` is strictly greater than `b` (compares global, then client). */
+export declare const isGreaterThan: (a: Composite, b: Composite) => boolean;
+/** Returns true if `a` is greater than or equal to `b` (compares global, then client). */
+export declare const isGreaterThanOrEqual: (a: Composite, b: Composite) => boolean;
+/** Returns the larger of two Composite sequence numbers. */
+export declare const max: (a: Composite, b: Composite) => Composite;
+/** Returns the difference between two Composite sequence numbers (a - b) for global and client components. */
+export declare const diff: (a: Composite, b: Composite) => {
+    global: number;
+    client: number;
+};
+/**
+ * Schema for the composite event sequence number.
+ * NOTE: Client mutation events with a non-0 client id won't be synced to the sync backend.
+ */
+declare const CompositeSchema: S.Struct<{
+    readonly global: S.brand<S.Int, "GlobalEventSequenceNumber">;
+    /** Only increments for client-local events */
+    readonly client: S.brand<S.Int, "ClientEventSequenceNumber">;
+    readonly rebaseGeneration: S.Int;
+}>;
+/**
+ * Effect Schema for the composite event sequence number (global + client + rebaseGeneration).
+ * Also includes a `make` helper for creating validated Composite values.
+ *
+ * @example
+ * ```ts
+ * const seqNum: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0
+ * }
+ *
+ * const validated = EventSequenceNumber.Client.Composite.make({ global: 5, client: 0, rebaseGeneration: 0 })
+ * ```
+ */
+export declare const Composite: S.Struct<{
+    readonly global: S.brand<S.Int, "GlobalEventSequenceNumber">;
+    /** Only increments for client-local events */
+    readonly client: S.brand<S.Int, "ClientEventSequenceNumber">;
+    readonly rebaseGeneration: S.Int;
+}> & {
+    make: (seqNum: CompositeInput) => Composite;
+};
+/** The root sequence number (global=0, client=0, rebaseGeneration=0). Parent of the first event. */
+export declare const ROOT: {
+    global: Global;
+    client: Type;
+    rebaseGeneration: number;
+};
+/**
+ * Computes the next sequence number and its parent based on the current position.
+ *
+ * For client-only events (isClientOnly=true): increments the client component, keeps global.
+ * For global events (isClientOnly=false): increments global, resets client to 0.
+ */
+export declare const nextPair: ({ seqNum, isClientOnly, rebaseGeneration, }: {
+    seqNum: Composite;
+    isClientOnly: boolean;
+    rebaseGeneration?: number;
+}) => CompositePair;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/schema/EventSequenceNumber/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/schema/EventSequenceNumber/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,EAAE,KAAK,IAAI,IAAI,MAAM,EAA8C,MAAM,aAAa,CAAA;AAE7F,8DAA8D;AAC9D,MAAM,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAA;AAIrE,mEAAmE;AACnE,eAAO,MAAM,MAAM,6CAA+D,CAAA;AAElF;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,yBAAc,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,MAAU,CAAA;AAE9B,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,IAAI,CAAA;IACZ;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,6GAA6G;AAC7G,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,CAAC,IAAI,CAAC,OAAO,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,GAAG;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAE9F,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,SAAS,CAAA;CAAE,CAAA;AAE1E;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,WAQjD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,SAAS,WAKzC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,SAyCxC,CAAA;AAED,wGAAwG;AACxG,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,SAI1C,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,OAAO,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,YAC2C,CAAA;AAE7F,uFAAuF;AACvF,eAAO,MAAM,aAAa,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,YAEvD,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,YAE9D,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,GAAG,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,cAE7C,CAAA;AAED,8GAA8G;AAC9G,eAAO,MAAM,IAAI,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS;;;CAK9C,CAAA;AAED;;;GAGG;AACH,QAAA,MAAM,eAAe;;IAEnB,8CAA8C;;;EAMkB,CAAA;AAelE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS;;IApCpB,8CAA8C;;;;mBAYjB,cAAc,KAAG,SAAS;CAwBuB,CAAA;AAEhF,oGAAoG;AACpG,eAAO,MAAM,IAAI;;;;CAII,CAAA;AAErB;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,6CAItB;IACD,MAAM,EAAE,SAAS,CAAA;IACjB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,KAAG,aAqBH,CAAA"}