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

package/dist/schema/EventDef/define.js

@@ -0,0 +1,140 @@
+/**
+ * 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 { Result, 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.decodeResult(Schema.toType(schema))(args);
+        if (Result.isFailure(res) === true) {
+            shouldNeverHappen(`Invalid event args for event '${name}':`, res.failure.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 !== undefined
+                ? (args, currentFacts) => {
+                    const res = options.facts(args, currentFacts);
+                    return {
+                        modify: {
+                            set: res.modify?.set !== undefined ? new Set(res.modify.set) : new Set(),
+                            unset: res.modify?.unset !== undefined ? new Set(res.modify.unset) : new Set(),
+                        },
+                        require: res.require !== undefined ? new Set(res.require) : new Set(),
+                    };
+                }
+                : undefined,
+            derived: options?.derived ?? false,
+            deprecated: options?.deprecated,
+        },
+    });
+    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.Literals(['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/define.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define.test.d.ts.map

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

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

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

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'vitest';
+import { Schema } from '@livestore/utils/effect';
+import { synced } from "./define.js";
+describe('synced event wire schema', () => {
+    const occurredAt = new Date('2026-07-17T10:15:30.000Z');
+    const event = synced({
+        name: 'v1.Occurred',
+        schema: Schema.Struct({
+            occurredAt: Schema.DateFromString,
+        }),
+    });
+    const jsonSchema = Schema.fromJsonString(event.schema);
+    test('roundtrips a valid date through JSON', () => {
+        const encoded = Schema.encodeSync(jsonSchema)({ occurredAt });
+        expect(encoded).toBe('{"occurredAt":"2026-07-17T10:15:30.000Z"}');
+        expect(Schema.decodeSync(jsonSchema)(encoded)).toEqual({ occurredAt });
+    });
+    test('rejects invalid dates on encode and decode', () => {
+        expect(() => Schema.encodeSync(jsonSchema)({ occurredAt: new Date(Number.NaN) })).toThrow();
+        expect(() => Schema.decodeSync(jsonSchema)('{"occurredAt":"not-a-date"}')).toThrow();
+    });
+});
+//# sourceMappingURL=define.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.test.js","sourceRoot":"","sources":["../../../src/schema/EventDef/define.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAE/C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,0BAA0B,CAAC,CAAA;IACvD,MAAM,KAAK,GAAG,MAAM,CAAC;QACnB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,CAAC,cAAc;SAClC,CAAC;KACH,CAAC,CAAA;IACF,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAEtD,IAAI,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;QAE7D,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAA;QACjE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;QAC3F,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;IACtF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

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

@@ -0,0 +1,94 @@
+/**
+ * Deprecation Annotations for Events
+ *
+ * This module provides utilities for marking event fields and entire events as deprecated.
+ * When a deprecated field is used or a deprecated event is committed, a warning is logged.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ * import { deprecated } from '@livestore/common/schema'
+ *
+ * // Field-level deprecation
+ * const todoUpdated = Events.synced({
+ *   name: 'v1.TodoUpdated',
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     title: Schema.optional(Schema.String).pipe(deprecated("Use 'text' instead")),
+ *     text: Schema.optional(Schema.String),
+ *   }),
+ * })
+ *
+ * // Event-level deprecation
+ * const todoRenamed = Events.synced({
+ *   name: 'v1.TodoRenamed',
+ *   schema: Schema.Struct({ id: Schema.String, name: Schema.String }),
+ *   deprecated: "Use 'v1.TodoUpdated' instead",
+ * })
+ * ```
+ * @module
+ */
+import { type Schema, Effect, Option } from '@livestore/utils/effect';
+import type { EventDef } from './event-def.ts';
+/** Annotation key used to mark schemas as deprecated. */
+export declare const DeprecatedId = "livestore/schema/annotations/deprecated";
+/**
+ * Marks a schema field as deprecated with a reason message.
+ * When an event is committed with a deprecated field that has a value,
+ * a warning will be logged.
+ *
+ * Works with Schema fields, including optional fields from Schema.optional.
+ *
+ * @param reason - Explanation of why this field is deprecated and what to use instead
+ * @returns A function that adds the deprecation annotation to the schema
+ *
+ * @example
+ * ```ts
+ * const schema = Schema.Struct({
+ *   oldField: Schema.optional(Schema.String).pipe(deprecated("Use 'newField' instead")),
+ *   newField: Schema.optional(Schema.String),
+ * })
+ * ```
+ */
+export declare const deprecated: (reason: string) => <T extends Schema.Top>(schema: T) => T["Rebuild"];
+/**
+ * Checks if a schema has a deprecation annotation.
+ *
+ * @param schema - The schema to check
+ * @returns The deprecation reason if deprecated, None otherwise
+ */
+export declare const getDeprecatedReason: (schema: Schema.Top) => Option.Option<string>;
+/**
+ * Checks if a schema is deprecated.
+ *
+ * @param schema - The schema to check
+ * @returns true if the schema is deprecated
+ */
+export declare const isDeprecated: (schema: Schema.Top) => boolean;
+/**
+ * Finds deprecated fields with values in the given event arguments.
+ * This walks through a Struct schema and checks each property for deprecation.
+ *
+ * @param schema - The event schema (expected to be a Struct)
+ * @param args - The event arguments
+ * @returns Array of objects containing field name and deprecation reason
+ */
+export declare const findDeprecatedFieldsWithValues: (schema: Schema.Top, args: Record<string, unknown>) => Array<{
+    field: string;
+    reason: string;
+}>;
+/**
+ * Logs deprecation warnings for an event using Effect.logWarning.
+ * Checks both event-level and field-level deprecation, with deduplication.
+ *
+ * @param eventDef - The event definition to check
+ * @param args - The event arguments
+ * @returns An Effect that logs warnings for any deprecations found
+ */
+export declare const logDeprecationWarnings: (eventDef: EventDef.AnyWithoutFn, args: Record<string, unknown>) => Effect.Effect<void>;
+/**
+ * Resets the deprecation warning state. Useful for testing.
+ */
+export declare const resetDeprecationWarnings: () => void;
+//# sourceMappingURL=deprecated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deprecated.d.ts","sourceRoot":"","sources":["../../../src/schema/EventDef/deprecated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,EAAa,MAAM,yBAAyB,CAAA;AAEhF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAE9C,yDAAyD;AACzD,eAAO,MAAM,YAAY,4CAA4C,CAAA;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACpB,QAAQ,MAAM,MACd,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAG,CAAC,CAAC,SAAS,CACD,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,MAAM,CAAC,GAAG,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CACE,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,CAAC,GAAG,KAAG,OAAqD,CAAA;AAEvG;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GACzC,QAAQ,MAAM,CAAC,GAAG,EAClB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA2BzC,CAAA;AAQD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,QAAQ,CAAC,YAAY,EAC/B,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,IAAI,CA2BjB,CAAA;AAEJ;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAO,IAG3C,CAAA"}

package/dist/schema/EventDef/deprecated.js

@@ -0,0 +1,143 @@
+/**
+ * Deprecation Annotations for Events
+ *
+ * This module provides utilities for marking event fields and entire events as deprecated.
+ * When a deprecated field is used or a deprecated event is committed, a warning is logged.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ * import { deprecated } from '@livestore/common/schema'
+ *
+ * // Field-level deprecation
+ * const todoUpdated = Events.synced({
+ *   name: 'v1.TodoUpdated',
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     title: Schema.optional(Schema.String).pipe(deprecated("Use 'text' instead")),
+ *     text: Schema.optional(Schema.String),
+ *   }),
+ * })
+ *
+ * // Event-level deprecation
+ * const todoRenamed = Events.synced({
+ *   name: 'v1.TodoRenamed',
+ *   schema: Schema.Struct({ id: Schema.String, name: Schema.String }),
+ *   deprecated: "Use 'v1.TodoUpdated' instead",
+ * })
+ * ```
+ * @module
+ */
+import { Effect, Option, SchemaAST } from '@livestore/utils/effect';
+/** Annotation key used to mark schemas as deprecated. */
+export const DeprecatedId = 'livestore/schema/annotations/deprecated';
+/**
+ * Marks a schema field as deprecated with a reason message.
+ * When an event is committed with a deprecated field that has a value,
+ * a warning will be logged.
+ *
+ * Works with Schema fields, including optional fields from Schema.optional.
+ *
+ * @param reason - Explanation of why this field is deprecated and what to use instead
+ * @returns A function that adds the deprecation annotation to the schema
+ *
+ * @example
+ * ```ts
+ * const schema = Schema.Struct({
+ *   oldField: Schema.optional(Schema.String).pipe(deprecated("Use 'newField' instead")),
+ *   newField: Schema.optional(Schema.String),
+ * })
+ * ```
+ */
+export const deprecated = (reason) => (schema) => schema.annotate({ [DeprecatedId]: reason });
+/**
+ * Checks if a schema has a deprecation annotation.
+ *
+ * @param schema - The schema to check
+ * @returns The deprecation reason if deprecated, None otherwise
+ */
+export const getDeprecatedReason = (schema) => Option.fromUndefinedOr(SchemaAST.resolveAt(DeprecatedId)(schema.ast));
+/**
+ * Checks if a schema is deprecated.
+ *
+ * @param schema - The schema to check
+ * @returns true if the schema is deprecated
+ */
+export const isDeprecated = (schema) => Option.isSome(getDeprecatedReason(schema));
+/**
+ * Finds deprecated fields with values in the given event arguments.
+ * This walks through a Struct schema and checks each property for deprecation.
+ *
+ * @param schema - The event schema (expected to be a Struct)
+ * @param args - The event arguments
+ * @returns Array of objects containing field name and deprecation reason
+ */
+export const findDeprecatedFieldsWithValues = (schema, args) => {
+    const result = [];
+    const ast = SchemaAST.toType(schema.ast);
+    // Handle Objects (Struct) schemas
+    if (SchemaAST.isObjects(ast) === true) {
+        for (const prop of ast.propertySignatures) {
+            const fieldName = String(prop.name);
+            const fieldValue = args[fieldName];
+            // Only check fields that have a value (not undefined)
+            if (fieldValue !== undefined) {
+                // Check deprecation on the property key itself (for Schema.optional(...).pipe(deprecated(...)))
+                const deprecationReason = prop.type.context?.annotations?.[DeprecatedId];
+                // Also check deprecation on the type (for direct field deprecation)
+                const typeDeprecation = SchemaAST.resolveAt(DeprecatedId)(prop.type);
+                const reason = deprecationReason ?? typeDeprecation;
+                if (reason !== undefined) {
+                    result.push({ field: fieldName, reason });
+                }
+            }
+        }
+    }
+    return result;
+};
+/** Set of event names that have already logged deprecation warnings. */
+const warnedDeprecatedEvents = new Set();
+/** Map of event+field combinations that have already logged deprecation warnings. */
+const warnedDeprecatedFields = new Set();
+/**
+ * Logs deprecation warnings for an event using Effect.logWarning.
+ * Checks both event-level and field-level deprecation, with deduplication.
+ *
+ * @param eventDef - The event definition to check
+ * @param args - The event arguments
+ * @returns An Effect that logs warnings for any deprecations found
+ */
+export const logDeprecationWarnings = (eventDef, args) => Effect.gen(function* () {
+    const eventName = eventDef.name;
+    // Check for event-level deprecation
+    const eventDeprecation = eventDef.options.deprecated;
+    if (eventDeprecation !== undefined && warnedDeprecatedEvents.has(eventName) === false) {
+        warnedDeprecatedEvents.add(eventName);
+        yield* Effect.logWarning('@livestore/schema:deprecated-event', {
+            event: eventName,
+            reason: eventDeprecation,
+        });
+    }
+    // Check for deprecated fields with values
+    const deprecatedFields = findDeprecatedFieldsWithValues(eventDef.schema, args);
+    for (const { field, reason } of deprecatedFields) {
+        const key = `${eventName}:${field}`;
+        if (warnedDeprecatedFields.has(key) === false) {
+            warnedDeprecatedFields.add(key);
+            yield* Effect.logWarning('@livestore/schema:deprecated-field', {
+                event: eventName,
+                field,
+                reason,
+            });
+        }
+    }
+});
+/**
+ * Resets the deprecation warning state. Useful for testing.
+ */
+export const resetDeprecationWarnings = () => {
+    warnedDeprecatedEvents.clear();
+    warnedDeprecatedFields.clear();
+};
+//# sourceMappingURL=deprecated.js.map

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

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

package/dist/schema/EventDef/deprecated.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deprecated.test.d.ts.map

package/dist/schema/EventDef/deprecated.test.d.ts.map

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

package/dist/schema/EventDef/deprecated.test.js

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { Effect, Logger, Schema } from '@livestore/utils/effect';
+import { synced } from "./define.js";
+import { deprecated, findDeprecatedFieldsWithValues, getDeprecatedReason, isDeprecated, logDeprecationWarnings, resetDeprecationWarnings, } from "./deprecated.js";
+describe('deprecated annotations', () => {
+    test('adds deprecation annotation to schema', () => {
+        const schema = Schema.String.pipe(deprecated('Use newField instead'));
+        expect(isDeprecated(schema)).toBe(true);
+        expect(getDeprecatedReason(schema)._tag).toBe('Some');
+    });
+    test('works with optional fields in Struct', () => {
+        const struct = Schema.Struct({
+            oldField: Schema.optional(Schema.String).pipe(deprecated('Legacy')),
+        });
+        expect(findDeprecatedFieldsWithValues(struct, { oldField: 'x' })).toEqual([{ field: 'oldField', reason: 'Legacy' }]);
+    });
+    test('non-deprecated schemas return false', () => {
+        expect(isDeprecated(Schema.String)).toBe(false);
+    });
+    test('ignores deprecated fields without values', () => {
+        const schema = Schema.Struct({
+            id: Schema.String,
+            old: Schema.optional(Schema.String).pipe(deprecated('x')),
+        });
+        expect(findDeprecatedFieldsWithValues(schema, { id: '1' })).toEqual([]);
+    });
+    test('finds multiple deprecated fields', () => {
+        const schema = Schema.Struct({
+            a: Schema.optional(Schema.String).pipe(deprecated('A')),
+            b: Schema.optional(Schema.String).pipe(deprecated('B')),
+        });
+        const result = findDeprecatedFieldsWithValues(schema, { a: '1', b: '2' });
+        expect(result).toHaveLength(2);
+    });
+});
+describe('logDeprecationWarnings', () => {
+    let logs;
+    beforeEach(() => {
+        resetDeprecationWarnings();
+        logs = [];
+    });
+    afterEach(() => resetDeprecationWarnings());
+    const run = (effect) => Effect.runSync(effect.pipe(Effect.provide(Logger.layer([Logger.make(({ message }) => logs.push(message))]))));
+    test('logs event deprecation warning', () => {
+        const event = synced({ name: 'Old', schema: Schema.Struct({ id: Schema.String }), deprecated: 'Use New' });
+        run(logDeprecationWarnings(event, { id: '1' }));
+        expect(logs).toEqual([['@livestore/schema:deprecated-event', { event: 'Old', reason: 'Use New' }]]);
+    });
+    test('logs field deprecation warning', () => {
+        const event = synced({
+            name: 'Ev',
+            schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('Use new')) }),
+        });
+        run(logDeprecationWarnings(event, { old: 'x' }));
+        expect(logs).toEqual([['@livestore/schema:deprecated-field', { event: 'Ev', field: 'old', reason: 'Use new' }]]);
+    });
+    test('deduplicates event warnings', () => {
+        const event = synced({ name: 'Dup', schema: Schema.Struct({ id: Schema.String }), deprecated: 'x' });
+        run(logDeprecationWarnings(event, { id: '1' }));
+        run(logDeprecationWarnings(event, { id: '2' }));
+        expect(logs).toHaveLength(1);
+    });
+    test('deduplicates field warnings', () => {
+        const event = synced({
+            name: 'DupField',
+            schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('x')) }),
+        });
+        run(logDeprecationWarnings(event, { old: 'a' }));
+        run(logDeprecationWarnings(event, { old: 'b' }));
+        expect(logs).toHaveLength(1);
+    });
+    test('no warning for non-deprecated event', () => {
+        const event = synced({ name: 'Normal', schema: Schema.Struct({ id: Schema.String }) });
+        run(logDeprecationWarnings(event, { id: '1' }));
+        expect(logs).toHaveLength(0);
+    });
+    test('no warning when deprecated field is undefined', () => {
+        const event = synced({
+            name: 'Unused',
+            schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('x')) }),
+        });
+        run(logDeprecationWarnings(event, {}));
+        expect(logs).toHaveLength(0);
+    });
+    test('logs both event and field warnings', () => {
+        const event = synced({
+            name: 'Both',
+            schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('F')) }),
+            deprecated: 'E',
+        });
+        run(logDeprecationWarnings(event, { old: 'x' }));
+        expect(logs).toHaveLength(2);
+    });
+});
+//# sourceMappingURL=deprecated.test.js.map

package/dist/schema/EventDef/deprecated.test.js.map

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

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

@@ -0,0 +1,110 @@
+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.Codec<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;
+        /**
+         * Deprecation reason for this event. When set, a warning is logged at commit time.
+         */
+        deprecated: string | undefined;
+    };
+    /**
+     * 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,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAErC,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;QAEjB;;WAEG;QACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;KAC/B,CAAA;IAED;;;OAGG;IACH,CAAC,IAAI,EAAE,KAAK,GAAG;QACb,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"}