@livestore/common 0.4.0-dev.2 → 0.4.0-dev.20

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

@@ -0,0 +1,147 @@
+/**
+ * Event Definition Functions
+ *
+ * This module provides functions for creating event definitions in LiveStore.
+ * Events are the core unit of state change - all mutations to the database
+ * happen through events that are committed to the eventlog.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * // Define events for your application
+ * export const events = {
+ *   // Synced events are sent to the sync backend
+ *   todoCreated: Events.synced({
+ *     name: 'v1.TodoCreated',
+ *     schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+ *   }),
+ *
+ *   // Client-only events stay local (useful for UI state)
+ *   uiStateSet: Events.clientOnly({
+ *     name: 'UiStateSet',
+ *     schema: Schema.Struct({ selectedId: Schema.NullOr(Schema.String) }),
+ *   }),
+ * }
+ * ```
+ * @module
+ */
+import { Schema } from '@livestore/utils/effect';
+import type { EventDef } from './event-def.ts';
+import type { EventDefFactInput, EventDefFacts } from './facts.ts';
+/** Options for defining an event. */
+export type DefineEventOptions<TTo, TDerived extends boolean = false> = {
+    /**
+     * Callback defining fact constraints for this event.
+     * @experimental This feature is not fully implemented yet.
+     */
+    facts?: (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 for this event to be valid.
+         * Used for history constraints and compaction rules.
+         */
+        require?: Iterable<EventDefFactInput>;
+    };
+    /**
+     * When true, the event is only synced within the same client's sessions
+     * but never sent to the sync backend. Useful for UI state.
+     * @default false
+     */
+    clientOnly?: boolean;
+    /**
+     * When true, marks this as a derived event that cannot have materializers.
+     * @default false
+     */
+    derived?: TDerived;
+};
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const customEvent = defineEvent({
+ *   name: 'v1.CustomEvent',
+ *   schema: Schema.Struct({ data: Schema.String }),
+ *   clientOnly: false,
+ *   derived: false,
+ * })
+ * ```
+ */
+export declare const defineEvent: <TName extends string, TType, TEncoded = TType, TDerived extends boolean = false>(args: {
+    name: TName;
+    schema: Schema.Schema<TType, TEncoded>;
+} & DefineEventOptions<TType, TDerived>) => EventDef<TName, TType, TEncoded, TDerived>;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * 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 }))
+ * ```
+ */
+export declare const synced: <TName extends string, TType, TEncoded = TType>(args: {
+    name: TName;
+    schema: Schema.Schema<TType, TEncoded>;
+} & Omit<DefineEventOptions<TType, false>, "derived" | "clientOnly">) => EventDef<TName, TType, TEncoded>;
+/**
+ * Creates a client-only event definition.
+ *
+ * Client-only events are synced within the same client's sessions (e.g., across
+ * browser tabs) but are never sent to the sync backend. Use this for local UI
+ * state like selected items, filter settings, or draft content.
+ *
+ * Note: Client-only events still require materializers and are stored in the
+ * local eventlog, they just don't participate in server-side sync.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * const uiStateSet = Events.clientOnly({
+ *   name: 'UiStateSet',
+ *   schema: Schema.Struct({
+ *     selectedTodoId: Schema.NullOr(Schema.String),
+ *     filterMode: Schema.Literal('all', 'active', 'completed'),
+ *   }),
+ * })
+ *
+ * // Update local UI state
+ * store.commit(uiStateSet({ selectedTodoId: 'abc', filterMode: 'active' }))
+ * ```
+ */
+export declare const clientOnly: <TName extends string, TType, TEncoded = TType>(args: {
+    name: TName;
+    schema: Schema.Schema<TType, TEncoded>;
+} & Omit<DefineEventOptions<TType, false>, "derived" | "clientOnly">) => EventDef<TName, TType, TEncoded>;
+//# sourceMappingURL=define.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAElE,qCAAqC;AACrC,MAAM,MAAM,kBAAkB,CAAC,GAAG,EAAE,QAAQ,SAAS,OAAO,GAAG,KAAK,IAAI;IACtE;;;OAGG;IACH,KAAK,CAAC,EAAE,CACN,IAAI,EAAE,GAAG,EACT,YAAY,EAAE,aAAa,KACxB;QACH,MAAM,CAAC,EAAE;YACP,uCAAuC;YACvC,GAAG,CAAC,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;YACjC,+BAA+B;YAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;SACpC,CAAA;QACD;;;WAGG;QACH,OAAO,CAAC,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;KACtC,CAAA;IAED;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,EAAE,QAAQ,SAAS,OAAO,GAAG,KAAK,EACzG,MAAM;IACJ,IAAI,EAAE,KAAK,CAAA;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CACvC,GAAG,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,KACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAqC3C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,EAClE,MAAM;IACJ,IAAI,EAAE,KAAK,CAAA;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CACvC,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC,KACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAgD,CAAA;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,EACtE,MAAM;IACJ,IAAI,EAAE,KAAK,CAAA;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CACvC,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC,KACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAA+C,CAAA"}

package/dist/schema/EventDef/define.js

@@ -0,0 +1,139 @@
+/**
+ * Event Definition Functions
+ *
+ * This module provides functions for creating event definitions in LiveStore.
+ * Events are the core unit of state change - all mutations to the database
+ * happen through events that are committed to the eventlog.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * // Define events for your application
+ * export const events = {
+ *   // Synced events are sent to the sync backend
+ *   todoCreated: Events.synced({
+ *     name: 'v1.TodoCreated',
+ *     schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+ *   }),
+ *
+ *   // Client-only events stay local (useful for UI state)
+ *   uiStateSet: Events.clientOnly({
+ *     name: 'UiStateSet',
+ *     schema: Schema.Struct({ selectedId: Schema.NullOr(Schema.String) }),
+ *   }),
+ * }
+ * ```
+ * @module
+ */
+import { shouldNeverHappen } from '@livestore/utils';
+import { Schema } from '@livestore/utils/effect';
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const customEvent = defineEvent({
+ *   name: 'v1.CustomEvent',
+ *   schema: Schema.Struct({ data: Schema.String }),
+ *   clientOnly: false,
+ *   derived: false,
+ * })
+ * ```
+ */
+export const defineEvent = (args) => {
+    const { name, schema, ...options } = args;
+    const makePartialEvent = (args) => {
+        const res = Schema.validateEither(schema)(args);
+        if (res._tag === 'Left') {
+            shouldNeverHappen(`Invalid event args for event '${name}':`, res.left.message, '\n');
+        }
+        return { name: name, args };
+    };
+    Object.defineProperty(makePartialEvent, 'name', { value: name });
+    Object.defineProperty(makePartialEvent, 'schema', { value: schema });
+    Object.defineProperty(makePartialEvent, 'encoded', {
+        value: (args) => ({ name: name, args }),
+    });
+    Object.defineProperty(makePartialEvent, 'options', {
+        value: {
+            clientOnly: options?.clientOnly ?? false,
+            facts: options?.facts
+                ? (args, currentFacts) => {
+                    const res = options.facts(args, currentFacts);
+                    return {
+                        modify: {
+                            set: res.modify?.set ? new Set(res.modify.set) : new Set(),
+                            unset: res.modify?.unset ? new Set(res.modify.unset) : new Set(),
+                        },
+                        require: res.require ? new Set(res.require) : new Set(),
+                    };
+                }
+                : undefined,
+            derived: options?.derived ?? false,
+        },
+    });
+    return makePartialEvent;
+};
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * 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 }))
+ * ```
+ */
+export const synced = (args) => defineEvent({ ...args, clientOnly: false });
+/**
+ * Creates a client-only event definition.
+ *
+ * Client-only events are synced within the same client's sessions (e.g., across
+ * browser tabs) but are never sent to the sync backend. Use this for local UI
+ * state like selected items, filter settings, or draft content.
+ *
+ * Note: Client-only events still require materializers and are stored in the
+ * local eventlog, they just don't participate in server-side sync.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * const uiStateSet = Events.clientOnly({
+ *   name: 'UiStateSet',
+ *   schema: Schema.Struct({
+ *     selectedTodoId: Schema.NullOr(Schema.String),
+ *     filterMode: Schema.Literal('all', 'active', 'completed'),
+ *   }),
+ * })
+ *
+ * // Update local UI state
+ * store.commit(uiStateSet({ selectedTodoId: 'abc', filterMode: 'active' }))
+ * ```
+ */
+export const clientOnly = (args) => defineEvent({ ...args, clientOnly: true });
+//# sourceMappingURL=define.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/schema/EventDef/define.ts"],"names":[],"mappings":"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"}

package/dist/schema/EventDef/event-def.d.ts

@@ -0,0 +1,106 @@
+import type { Schema } from '@livestore/utils/effect';
+import type { FactsCallback } from './facts.ts';
+/**
+ * Core type representing an event definition in LiveStore.
+ *
+ * An EventDef defines the structure and behavior of an event type, including:
+ * - A unique name identifying the event type (conventionally versioned, e.g., `v1.TodoCreated`)
+ * - A schema for validating and encoding/decoding event arguments
+ * - Options controlling sync behavior and constraints
+ *
+ * EventDefs are callable - invoking them creates a partial event object suitable for `store.commit()`.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * const todoCreated = Events.synced({
+ *   name: 'v1.TodoCreated',
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     text: Schema.String,
+ *   }),
+ * })
+ *
+ * // Use the EventDef as a constructor
+ * store.commit(todoCreated({ id: 'abc', text: 'Buy milk' }))
+ * ```
+ */
+export type EventDef<TName extends string, TType, TEncoded = TType, TDerived extends boolean = false> = {
+    /** Unique identifier for this event type. Conventionally versioned (e.g., `v1.TodoCreated`). */
+    name: TName;
+    /** Effect Schema used for validating and encoding/decoding event arguments. */
+    schema: Schema.Schema<TType, TEncoded>;
+    options: {
+        /**
+         * When true, the event is only synced within the same client's sessions (e.g., across tabs)
+         * but never sent to the sync backend. Useful for UI state like selected items or filters.
+         */
+        clientOnly: boolean;
+        /**
+         * Callback defining fact constraints for this event.
+         * @experimental This feature is not fully implemented yet.
+         */
+        facts: FactsCallback<TType> | undefined;
+        /** Whether this is a derived event. Derived events cannot have materializers. */
+        derived: TDerived;
+    };
+    /**
+     * Callable signature - creates a partial event with decoded arguments.
+     * The returned object can be passed directly to `store.commit()`.
+     */
+    (args: TType): {
+        name: TName;
+        args: TType;
+    };
+    /**
+     * Creates a partial event with pre-encoded arguments.
+     * Useful when working with already-serialized data.
+     */
+    encoded: (args: TEncoded) => {
+        name: TName;
+        args: TEncoded;
+    };
+    /** Type helper for accessing the event's shape with name and decoded args. */
+    readonly Event: {
+        name: TName;
+        args: TType;
+    };
+};
+export declare namespace EventDef {
+    /**
+     * Wildcard type matching any EventDef regardless of type parameters.
+     * Used as a type constraint in generic functions and collections.
+     */
+    type Any = EventDef<string, any, any, boolean>;
+    /**
+     * EventDef without the callable function signature.
+     * Used in contexts where only the metadata (name, schema, options) is needed,
+     * such as materializer definitions.
+     */
+    type AnyWithoutFn = Pick<Any, 'name' | 'schema' | 'options'>;
+}
+/**
+ * Container holding a Map of event definitions keyed by name.
+ * Used internally by LiveStoreSchema.
+ */
+export type EventDefMap = {
+    map: Map<string, EventDef.Any>;
+};
+/**
+ * Plain object record of event definitions keyed by name.
+ * This is the typical shape when defining events in user code.
+ *
+ * @example
+ * ```ts
+ * const events = {
+ *   todoCreated: Events.synced({ name: 'v1.TodoCreated', schema: ... }),
+ *   todoDeleted: Events.synced({ name: 'v1.TodoDeleted', schema: ... }),
+ * } satisfies EventDefRecord
+ * ```
+ */
+export type EventDefRecord = {
+    [name: string]: EventDef.Any;
+};
+//# sourceMappingURL=event-def.d.ts.map

package/dist/schema/EventDef/event-def.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-def.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/event-def.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,EAAE,QAAQ,SAAS,OAAO,GAAG,KAAK,IAAI;IACtG,gGAAgG;IAChG,IAAI,EAAE,KAAK,CAAA;IAEX,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAEtC,OAAO,EAAE;QACP;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAA;QAEnB;;;WAGG;QACH,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;QAEvC,iFAAiF;QACjF,OAAO,EAAE,QAAQ,CAAA;KAClB,CAAA;IAED;;;OAGG;IACH,CACE,IAAI,EAAE,KAAK,GACV;QACD,IAAI,EAAE,KAAK,CAAA;QACX,IAAI,EAAE,KAAK,CAAA;KACZ,CAAA;IAED;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK;QAC3B,IAAI,EAAE,KAAK,CAAA;QACX,IAAI,EAAE,QAAQ,CAAA;KACf,CAAA;IAED,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE;QACd,IAAI,EAAE,KAAK,CAAA;QACX,IAAI,EAAE,KAAK,CAAA;KACZ,CAAA;CACF,CAAA;AAED,yBAAiB,QAAQ,CAAC;IACxB;;;OAGG;IACH,KAAY,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IAErD;;;;OAIG;IACH,KAAY,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAA;CACpE;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAA;CAC7B,CAAA"}

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"}