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

package/src/schema/EventDef/deprecated.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+
+import { Effect, Logger, Schema } from '@livestore/utils/effect'
+
+import { synced } from './define.ts'
+import {
+  deprecated,
+  findDeprecatedFieldsWithValues,
+  getDeprecatedReason,
+  isDeprecated,
+  logDeprecationWarnings,
+  resetDeprecationWarnings,
+} from './deprecated.ts'
+
+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: unknown[][]
+
+  beforeEach(() => {
+    resetDeprecationWarnings()
+    logs = []
+  })
+
+  afterEach(() => resetDeprecationWarnings())
+
+  const run = (effect: Effect.Effect<void>) =>
+    Effect.runSync(
+      effect.pipe(Effect.provide(Logger.layer([Logger.make(({ message }) => logs.push(message as unknown[]))]))),
+    )
+
+  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)
+  })
+})

package/src/schema/EventDef/deprecated.ts

@@ -0,0 +1,172 @@
+/**
+ * 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, SchemaAST } from '@livestore/utils/effect'
+
+import type { EventDef } from './event-def.ts'
+
+/** 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: string) =>
+  <T extends Schema.Top>(schema: T): T['Rebuild'] =>
+    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: Schema.Top): Option.Option<string> =>
+  Option.fromUndefinedOr(SchemaAST.resolveAt<string>(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: Schema.Top): boolean => 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: Schema.Top,
+  args: Record<string, unknown>,
+): Array<{ field: string; reason: string }> => {
+  const result: Array<{ field: string; reason: string }> = []
+  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] as string | undefined
+
+        // Also check deprecation on the type (for direct field deprecation)
+        const typeDeprecation = SchemaAST.resolveAt<string>(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<string>()
+
+/** Map of event+field combinations that have already logged deprecation warnings. */
+const warnedDeprecatedFields = new Set<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 const logDeprecationWarnings = (
+  eventDef: EventDef.AnyWithoutFn,
+  args: Record<string, unknown>,
+): Effect.Effect<void> =>
+  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 = (): void => {
+  warnedDeprecatedEvents.clear()
+  warnedDeprecatedFields.clear()
+}

package/src/schema/EventDef/event-def.ts

@@ -0,0 +1,123 @@
+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 namespace EventDef {
+  /**
+   * Wildcard type matching any EventDef regardless of type parameters.
+   * Used as a type constraint in generic functions and collections.
+   */
+  export 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.
+   */
+  export 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
+}

package/src/schema/EventDef/facts.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 const defineFacts = <
+  TRecord extends Record<string, EventDefFactInput | ((...args: any[]) => EventDefFactInput)>,
+>(
+  record: TRecord,
+): TRecord => record