@livestore/common 0.4.0-dev.1 → 0.4.0-dev.10

package/src/schema/state/sqlite/query-builder/impl.test.ts

@@ -409,9 +409,7 @@ describe('query builder', () => {
     })
 
     it('should handle INSERT queries with undefined values', () => {
-      expect(
-        dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active', completed: undefined })),
-      ).toMatchInlineSnapshot(`
+      expect(dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }))).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "123",
@@ -478,9 +476,7 @@ describe('query builder', () => {
     })
 
     it('should handle UPDATE queries with undefined values', () => {
-      expect(
-        dump(db.todos.update({ status: undefined, text: 'some text' }).where({ id: '123' })),
-      ).toMatchInlineSnapshot(`
+      expect(dump(db.todos.update({ text: 'some text' }).where({ id: '123' }))).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "some text",
@@ -622,6 +618,191 @@ describe('query builder', () => {
         }
       `)
     })
+
+    it('should handle where().delete() - preserving where clauses', () => {
+      expect(dump(db.todos.where({ status: 'completed' }).delete())).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+          ],
+          "query": "DELETE FROM 'todos' WHERE status = ?",
+          "schema": "number",
+        }
+      `)
+
+      // Multiple where clauses
+      expect(dump(db.todos.where({ status: 'completed' }).where({ deletedAt: null }).delete())).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+          ],
+          "query": "DELETE FROM 'todos' WHERE status = ? AND deletedAt IS NULL",
+          "schema": "number",
+        }
+      `)
+    })
+
+    it('should handle where().update() - preserving where clauses', () => {
+      expect(dump(db.todos.where({ id: '123' }).update({ status: 'completed' }))).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+            "123",
+          ],
+          "query": "UPDATE 'todos' SET status = ? WHERE id = ?",
+          "schema": "number",
+        }
+      `)
+
+      // Multiple where clauses
+      expect(
+        dump(db.todos.where({ id: '123' }).where({ deletedAt: null }).update({ status: 'completed' })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+            "123",
+          ],
+          "query": "UPDATE 'todos' SET status = ? WHERE id = ? AND deletedAt IS NULL",
+          "schema": "number",
+        }
+      `)
+    })
+
+    it('should have equivalent behavior for both delete patterns', () => {
+      const pattern1 = dump(db.todos.where({ status: 'completed', id: '123' }).delete())
+      const pattern2 = dump(db.todos.delete().where({ status: 'completed', id: '123' }))
+
+      expect(pattern1).toEqual(pattern2)
+    })
+
+    it('should have equivalent behavior for both update patterns', () => {
+      const pattern1 = dump(db.todos.where({ id: '123' }).update({ status: 'completed', text: 'Updated' }))
+      const pattern2 = dump(db.todos.update({ status: 'completed', text: 'Updated' }).where({ id: '123' }))
+
+      expect(pattern1).toEqual(pattern2)
+    })
+  })
+
+  describe('schema transforms', () => {
+    const Flat = Schema.Struct({
+      id: Schema.String.pipe(State.SQLite.withPrimaryKey),
+      contactFirstName: Schema.String,
+      contactLastName: Schema.String,
+      contactEmail: Schema.String.pipe(State.SQLite.withUnique),
+    })
+
+    const Nested = Schema.transform(
+      Flat,
+      Schema.Struct({
+        id: Schema.String,
+        contact: Schema.Struct({
+          firstName: Schema.String,
+          lastName: Schema.String,
+          email: Schema.String,
+        }),
+      }),
+      {
+        decode: ({ id, contactFirstName, contactLastName, contactEmail }) => ({
+          id,
+          contact: {
+            firstName: contactFirstName,
+            lastName: contactLastName,
+            email: contactEmail,
+          },
+        }),
+        encode: ({ id, contact }) => ({
+          id,
+          contactFirstName: contact.firstName,
+          contactLastName: contact.lastName,
+          contactEmail: contact.email,
+        }),
+      },
+    )
+
+    const makeContactsTable = () =>
+      State.SQLite.table({
+        name: 'contacts',
+        schema: Nested,
+        // schema: Flat,
+      })
+
+    it('exposes flattened insert type while schema type is nested', () => {
+      const contactsTable = makeContactsTable()
+
+      type InsertInput = Parameters<(typeof contactsTable)['insert']>[0]
+      type NestedType = Schema.Schema.Type<typeof Nested>
+
+      type Assert<T extends true> = T
+
+      type InsertKeys = keyof InsertInput
+      type NestedKeys = keyof NestedType
+
+      type _InsertHasFlattenedColumns = Assert<
+        'contactFirstName' extends InsertKeys
+          ? 'contactLastName' extends InsertKeys
+            ? 'contactEmail' extends InsertKeys
+              ? true
+              : false
+            : false
+          : false
+      >
+
+      type _InsertDoesNotExposeNested = Assert<Extract<'contact', InsertKeys> extends never ? true : false>
+
+      type _SchemaTypeIsNested = Assert<'contact' extends NestedKeys ? true : false>
+
+      void contactsTable
+    })
+
+    it('fails to encode nested inserts because flat columns are required', () => {
+      const contactsTable = makeContactsTable()
+
+      expect(
+        contactsTable
+          // TODO in the future we should use decoded types here instead of encoded
+          .insert({
+            id: 'person-1',
+            contactFirstName: 'Ada',
+            contactLastName: 'Lovelace',
+            contactEmail: 'ada@example.com',
+          })
+          .asSql(),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "person-1",
+            "Ada",
+            "Lovelace",
+            "ada@example.com",
+          ],
+          "query": "INSERT INTO 'contacts' (id, contactFirstName, contactLastName, contactEmail) VALUES (?, ?, ?, ?)",
+          "usedTables": Set {
+            "contacts",
+          },
+        }
+      `)
+    })
+
+    it('fails to encode nested inserts because flat columns are required', () => {
+      const contactsTable = makeContactsTable()
+
+      expect(() =>
+        contactsTable
+          .insert({
+            id: 'person-1',
+            // @ts-expect-error
+            contact: {
+              firstName: 'Ada',
+              lastName: 'Lovelace',
+              email: 'ada@example.com',
+            },
+          })
+          .asSql(),
+      ).toThrowErrorMatchingInlineSnapshot(`
+        [ParseError: contacts\n└─ ["contactFirstName"]\n   └─ is missing]
+      `)
+    })
   })
 })
 

package/src/schema/state/sqlite/query-builder/impl.ts

@@ -219,21 +219,27 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
     update: (values) => {
       const filteredValues = Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined))
 
+      // Preserve where clauses if coming from a SelectQuery
+      const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
+
       return makeQueryBuilder(tableDef, {
         _tag: 'UpdateQuery',
         tableDef,
         values: filteredValues,
-        where: [],
+        where: whereClause,
         returning: undefined,
         resultSchema: Schema.Void,
       }) as any
     },
 
     delete: () => {
+      // Preserve where clauses if coming from a SelectQuery
+      const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
+
       return makeQueryBuilder(tableDef, {
         _tag: 'DeleteQuery',
         tableDef,
-        where: [],
+        where: whereClause,
         returning: undefined,
         resultSchema: Schema.Void,
       }) as any

package/src/schema/state/sqlite/system-tables.ts

@@ -96,6 +96,8 @@ export const syncStatusTable = table({
   name: SYNC_STATUS_TABLE,
   columns: {
     head: SqliteDsl.integer({ primaryKey: true }),
+    // Null means the sync backend is not yet connected and we haven't yet seen a backend ID
+    backendId: SqliteDsl.text({ nullable: true }),
   },
 })
 

package/src/schema/state/sqlite/table-def.test.ts

@@ -63,6 +63,7 @@ describe('table function overloads', () => {
         id: State.SQLite.text({ primaryKey: true }),
         text: State.SQLite.text({ default: '' }),
         completed: State.SQLite.boolean({ default: false }),
+        optionalBoolean: State.SQLite.boolean({ default: false, nullable: true }),
         optionalComplex: State.SQLite.json({
           nullable: true,
           schema: Schema.Struct({ color: Schema.String }).pipe(Schema.UndefinedOr),
@@ -76,7 +77,15 @@ describe('table function overloads', () => {
     expect(todosTable.sqliteDef.columns).toHaveProperty('text')
     expect(todosTable.sqliteDef.columns).toHaveProperty('completed')
     expect(todosTable.sqliteDef.columns).toHaveProperty('optionalComplex')
+
+    expect(todosTable.sqliteDef.columns.optionalBoolean.nullable).toBe(true)
+    expect(todosTable.sqliteDef.columns.optionalBoolean.schema.toString()).toBe('(number <-> boolean) | null')
+    expect((todosTable.rowSchema as any).fields.optionalBoolean.toString()).toBe('(number <-> boolean) | null')
+
     expect(todosTable.sqliteDef.columns.optionalComplex.nullable).toBe(true)
+    expect(todosTable.sqliteDef.columns.optionalComplex.schema.toString()).toBe(
+      '(parseJson <-> { readonly color: string } | undefined) | null',
+    )
     expect((todosTable.rowSchema as any).fields.optionalComplex.toString()).toBe(
       '(parseJson <-> { readonly color: string } | undefined) | null',
     )
@@ -169,6 +178,59 @@ describe('table function overloads', () => {
     expect(userTable.sqliteDef.columns.age.columnType).toBe('integer')
   })
 
+  it('should support schemas that transform flat columns into nested types', () => {
+    const Flat = Schema.Struct({
+      id: Schema.String.pipe(State.SQLite.withPrimaryKey),
+      contactFirstName: Schema.String,
+      contactLastName: Schema.String,
+      contactEmail: Schema.String.pipe(State.SQLite.withUnique),
+    })
+
+    const Nested = Schema.transform(
+      Flat,
+      Schema.Struct({
+        id: Schema.String,
+        contact: Schema.Struct({
+          firstName: Schema.String,
+          lastName: Schema.String,
+          email: Schema.String,
+        }),
+      }),
+      {
+        decode: ({ id, contactFirstName, contactLastName, contactEmail }) => ({
+          id,
+          contact: {
+            firstName: contactFirstName,
+            lastName: contactLastName,
+            email: contactEmail,
+          },
+        }),
+        encode: ({ id, contact }) => ({
+          id,
+          contactFirstName: contact.firstName,
+          contactLastName: contact.lastName,
+          contactEmail: contact.email,
+        }),
+      },
+    )
+
+    const contactsTable = State.SQLite.table({
+      name: 'contacts',
+      schema: Nested,
+    })
+
+    const columns = contactsTable.sqliteDef.columns
+
+    expect(Object.keys(columns)).toEqual(['id', 'contactFirstName', 'contactLastName', 'contactEmail'])
+    expect(columns.id.primaryKey).toBe(true)
+    expect(columns.contactEmail.columnType).toBe('text')
+    expect(contactsTable.sqliteDef.indexes).toContainEqual({
+      name: 'idx_contacts_contactEmail_unique',
+      columns: ['contactEmail'],
+      isUnique: true,
+    })
+  })
+
   it('should extract table name from Schema.Class identifier', () => {
     class TodoItem extends Schema.Class<TodoItem>('TodoItem')({
       id: Schema.String,
@@ -217,10 +279,10 @@ describe('table function overloads', () => {
     type MetadataColumn = typeof userTable.sqliteDef.columns.metadata
 
     // Should derive proper column schema
-    expect((userTable.rowSchema as any).fields.age.toString()).toMatchInlineSnapshot(`"number"`)
+    expect((userTable.rowSchema as any).fields.age.toString()).toMatchInlineSnapshot(`"Int"`)
     expect((userTable.rowSchema as any).fields.active.toString()).toMatchInlineSnapshot(`"(number <-> boolean)"`)
     expect((userTable.rowSchema as any).fields.metadata.toString()).toMatchInlineSnapshot(
-      `"(parseJson <-> { readonly [x: string]: unknown } | undefined)"`,
+      `"(parseJson <-> { readonly [x: string]: unknown }) | null"`,
     )
 
     // These should compile without errors

package/src/schema/state/sqlite/table-def.ts

@@ -1,5 +1,5 @@
 import { type Nullable, shouldNeverHappen } from '@livestore/utils'
-import { Option, type Schema, SchemaAST, type Types } from '@livestore/utils/effect'
+import { Option, Schema, SchemaAST, type Types } from '@livestore/utils/effect'
 
 import { getColumnDefForSchema, schemaFieldsToColumns } from './column-def.ts'
 import { SqliteDsl } from './db-schema/mod.ts'
@@ -221,7 +221,7 @@ export function table<
     ) as SqliteDsl.Columns
     additionalIndexes = []
   } else if ('schema' in args) {
-    const result = schemaFieldsToColumns(SchemaAST.getPropertySignatures(args.schema.ast))
+    const result = schemaFieldsToColumns(Schema.getResolvedPropertySignatures(args.schema))
     columns = result.columns
 
     // We'll set tableName first, then use it for index names
@@ -381,12 +381,13 @@ export declare namespace SchemaToColumns {
   export type ColumnDefForType<TEncoded, TType> = SqliteDsl.ColumnDefinition<TEncoded, TType>
 
   // Create columns type from schema Type and Encoded
-  export type FromTypes<TType, TEncoded> = TType extends Record<string, any>
-    ? TEncoded extends Record<string, any>
-      ? {
-          [K in keyof TType & keyof TEncoded]: ColumnDefForType<TEncoded[K], TType[K]>
-        }
-      : SqliteDsl.Columns
+  export type FromTypes<TType, TEncoded> = TEncoded extends Record<string, any>
+    ? {
+        [K in keyof TEncoded]-?: ColumnDefForType<
+          TEncoded[K],
+          TType extends Record<string, any> ? (K extends keyof TType ? TType[K] : TEncoded[K]) : TEncoded[K]
+        >
+      }
     : SqliteDsl.Columns
 }
 

package/src/schema/unknown-events.ts

@@ -0,0 +1,131 @@
+import { Effect } from '@livestore/utils/effect'
+
+import { UnknownEventError } from '../errors.ts'
+import type { EventDef, Materializer } from './EventDef.ts'
+import type * as LiveStoreEvent from './LiveStoreEvent.ts'
+import type { LiveStoreSchema } from './schema.ts'
+
+export type UnknownEventContext = {
+  readonly event: Pick<LiveStoreEvent.AnyEncoded, 'name' | 'args' | 'seqNum' | 'clientId' | 'sessionId'>
+  readonly reason: 'event-definition-missing' | 'materializer-missing'
+  readonly operation: string
+}
+
+export namespace UnknownEvents {
+  export type HandlingStrategy = 'warn' | 'fail' | 'ignore' | 'callback'
+
+  export type Callback = (
+    context: UnknownEventContext,
+    error: UnknownEventError,
+  ) => Effect.SyncOrPromiseOrEffect<void, unknown, never>
+
+  export type HandlingConfig =
+    | { readonly strategy: 'warn' }
+    | { readonly strategy: 'ignore' }
+    | { readonly strategy: 'fail' }
+    | { readonly strategy: 'callback'; readonly onUnknownEvent: Callback }
+
+  export type Reason = UnknownEventContext['reason']
+
+  export type ResolveContext = Omit<UnknownEventContext, 'reason'>
+
+  export type Resolved =
+    | {
+        readonly _tag: 'known'
+        readonly eventDef: EventDef.AnyWithoutFn
+        readonly materializer: Materializer
+      }
+    | {
+        readonly _tag: 'unknown'
+        readonly reason: Reason
+      }
+}
+
+const DEFAULT_UNKNOWN_EVENT_HANDLING: UnknownEvents.HandlingConfig = { strategy: 'warn' }
+
+export const normalizeUnknownEventHandling = (
+  input: UnknownEvents.HandlingConfig | undefined,
+): UnknownEvents.HandlingConfig => input ?? DEFAULT_UNKNOWN_EVENT_HANDLING
+
+const handleUnknownEvent = ({
+  schema,
+  context,
+}: {
+  schema: LiveStoreSchema
+  context: UnknownEventContext
+}): Effect.Effect<void, UnknownEventError> =>
+  Effect.gen(function* () {
+    const config = schema.unknownEventHandling
+    const error = new UnknownEventError(context)
+
+    switch (config.strategy) {
+      case 'fail': {
+        return yield* Effect.fail(error)
+      }
+      case 'warn': {
+        yield* Effect.logWarning('@livestore/common:schema:unknown-event', context)
+        return
+      }
+      case 'ignore': {
+        return
+      }
+      case 'callback': {
+        const callback = config.onUnknownEvent
+
+        yield* Effect.tryAll<void>(() => callback(context, error)).pipe(
+          Effect.catchAll((cause) =>
+            Effect.logWarning('@livestore/common:schema:unknown-event:callback-error', {
+              event: context.event,
+              reason: context.reason,
+              operation: context.operation,
+              cause,
+            }),
+          ),
+        )
+        return
+      }
+    }
+  })
+
+/**
+ * Resolves the runtime event definition + materializer for a given event name.
+ *
+ * Behaviour is intentionally split across the result and error channels:
+ * - For `'fail'` handling, we surface an `UnknownEventError` via the failure channel so
+ *   callers can convert it into the appropriate domain error (for example `MaterializeError`).
+ * - For all other strategies (`warn`, `ignore`, `callback`) we succeed with an
+ *   `{ _tag: 'unknown' }` value, signalling that the caller should skip the event while
+ *   continuing normal processing.
+ */
+export const resolveEventDef = (
+  schema: LiveStoreSchema,
+  context: UnknownEvents.ResolveContext,
+): Effect.Effect<UnknownEvents.Resolved, UnknownEventError> =>
+  Effect.gen(function* () {
+    const eventName = context.event.name
+    const eventDef = schema.eventsDefsMap.get(eventName)
+    if (eventDef === undefined) {
+      yield* handleUnknownEvent({
+        schema,
+        context: {
+          event: context.event,
+          reason: 'event-definition-missing',
+          operation: context.operation,
+        },
+      })
+      return { _tag: 'unknown', reason: 'event-definition-missing' }
+    }
+    const materializer = schema.state.materializers.get(eventName)
+    if (materializer === undefined) {
+      yield* handleUnknownEvent({
+        schema,
+        context: {
+          event: context.event,
+          reason: 'materializer-missing',
+          operation: context.operation,
+        },
+      })
+      return { _tag: 'unknown', reason: 'materializer-missing' }
+    }
+    return { _tag: 'known', eventDef, materializer }
+  })

package/src/sql-queries/sql-query-builder.ts

@@ -1,3 +1,4 @@
+import { omitUndefineds } from '@livestore/utils'
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import type { BindValues } from './sql-queries.ts'
 import * as SqlQueries from './sql-queries.ts'
@@ -16,7 +17,7 @@ export const makeSqlQueryBuilder = <TSchema extends SqliteDsl.DbSchema>(schema:
     limit?: number
   }): [string, BindValues, TTableName] => {
     const columns = schema[tableName]!.columns
-    const [stmt, bindValues] = SqlQueries.findManyRows({ columns, tableName, where, limit })
+    const [stmt, bindValues] = SqlQueries.findManyRows({ columns, tableName, where, ...omitUndefineds({ limit }) })
     return [stmt, bindValues, tableName]
   }