@livestore/common 0.3.2-dev.9 → 0.4.0-dev.1

package/src/schema/state/sqlite/client-document-def.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, test } from 'vitest'
 
 import { tables } from '../../../__tests__/fixture.ts'
 import type * as LiveStoreEvent from '../../LiveStoreEvent.ts'
-import { ClientDocumentTableDefSymbol, clientDocument } from './client-document-def.ts'
+import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
 
 describe('client document table', () => {
   test('set event', () => {
@@ -238,3 +238,91 @@ const patchId = (muationEvent: LiveStoreEvent.PartialAnyDecoded) => {
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }
 }
+
+describe('mergeDefaultValues', () => {
+  test('merges values from both objects', () => {
+    const defaults = { a: 1, b: 2 }
+    const explicit = { a: 10, b: 20 }
+    const result = mergeDefaultValues(defaults, explicit)
+
+    expect(result).toEqual({ a: 10, b: 20 })
+  })
+
+  test('uses default values when explicit values are undefined', () => {
+    const defaults = { a: 1, b: 2 }
+    const explicit = { a: undefined, b: 20 } as any
+    const result = mergeDefaultValues(defaults, explicit)
+
+    expect(result).toEqual({ a: 1, b: 20 })
+  })
+
+  test('should preserve properties that are not in default values', () => {
+    const defaults = { a: 1, b: 2 }
+    const explicit = { a: 10, b: 20, c: 30 }
+    const result = mergeDefaultValues(defaults, explicit)
+
+    // Should include ALL properties from explicit, not just those in defaults
+    expect(result).toEqual({ a: 10, b: 20, c: 30 })
+    expect('c' in result).toBe(true)
+  })
+
+  test('issue #487 - should preserve optional fields not in defaults', () => {
+    const defaults = {
+      newTodoText: '',
+      filter: 'all' as const,
+    }
+    const userSet = {
+      newTodoText: '',
+      description: 'First attempt', // Optional field not in defaults
+      filter: 'all' as const,
+    }
+    const result = mergeDefaultValues(defaults, userSet)
+
+    // Should include the description field even though it's not in defaults
+    expect(result).toEqual({
+      newTodoText: '',
+      description: 'First attempt',
+      filter: 'all',
+    })
+    expect('description' in result).toBe(true)
+  })
+
+  test('handles non-object values', () => {
+    expect(mergeDefaultValues('default', 'explicit')).toBe('explicit')
+    expect(mergeDefaultValues(42, 100)).toBe(100)
+    expect(mergeDefaultValues(null, { a: 1 })).toEqual({ a: 1 })
+    expect(mergeDefaultValues({ a: 1 }, null)).toBe(null)
+  })
+
+  test('handles nested objects (current implementation does not deep merge)', () => {
+    const defaults = { a: { x: 1, y: 2 }, b: 3 }
+    const explicit = { a: { x: 10 }, b: 30 } as any
+    const result = mergeDefaultValues(defaults, explicit)
+
+    // Current implementation replaces entire nested object
+    expect(result).toEqual({ a: { x: 10 }, b: 30 })
+    // Note: 'y' is lost because the entire 'a' object is replaced
+  })
+
+  test('should handle mix of default and new properties', () => {
+    const defaults = {
+      required1: 'default1',
+      required2: 'default2',
+    }
+    const userSet = {
+      required1: 'user1', // Override default
+      required2: 'default2', // Keep default
+      optional1: 'new1', // New field
+      optional2: 'new2', // New field
+    }
+    const result = mergeDefaultValues(defaults, userSet)
+
+    expect(result).toEqual({
+      required1: 'user1',
+      required2: 'default2',
+      optional1: 'new1',
+      optional2: 'new2',
+    })
+    expect(Object.keys(result).sort()).toEqual(['optional1', 'optional2', 'required1', 'required2'])
+  })
+})

package/src/schema/state/sqlite/client-document-def.ts

@@ -17,12 +17,12 @@ import { table } from './table-def.ts'
  * - Synced across client sessions (e.g. tabs) but not across different clients
  * - Derived setters
  *   - Emits client-only events
- *   - Has implicit setter-reducers
+ *   - Has implicit setter-materializers
  * - Similar to `React.useState` (except it's persisted)
  *
  * Careful:
  * - When changing the table definitions in a non-backwards compatible way, the state might be lost without
- *   explicit reducers to handle the old auto-generated events
+ *   explicit materializers to handle the old auto-generated events
  *
  * Usage:
  *
@@ -121,7 +121,7 @@ export const clientDocument = <
   return clientDocumentTableDef
 }
 
-const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T): T => {
+export const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T): T => {
   if (
     typeof defaultValues !== 'object' ||
     typeof explicitDefaultValues !== 'object' ||
@@ -131,7 +131,10 @@ const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T): T =>
     return explicitDefaultValues
   }
 
-  return Object.keys(defaultValues as any).reduce((acc, key) => {
+  // Get all unique keys from both objects
+  const allKeys = new Set([...Object.keys(defaultValues as any), ...Object.keys(explicitDefaultValues as any)])
+
+  return Array.from(allKeys).reduce((acc, key) => {
     acc[key] = (explicitDefaultValues as any)[key] ?? (defaultValues as any)[key]
     return acc
   }, {} as any)

package/src/schema/state/sqlite/column-annotations.test.ts

@@ -0,0 +1,212 @@
+import { Schema, SchemaAST } from '@livestore/utils/effect'
+import { describe, expect, test } from 'vitest'
+
+import { withColumnType, withPrimaryKey } from './column-annotations.ts'
+
+describe.concurrent('annotations', () => {
+  describe('withPrimaryKey', () => {
+    test('should add primary key annotation', () => {
+      const schema = Schema.String
+      const result = withPrimaryKey(schema)
+
+      expect(SchemaAST.annotations(result.ast, {})).toMatchInlineSnapshot(`
+        {
+          "_tag": "StringKeyword",
+          "annotations": {
+            "Symbol(effect/annotation/Description)": "a string",
+            "Symbol(effect/annotation/Title)": "string",
+            "Symbol(livestore/state/sqlite/annotations/primary-key)": true,
+          },
+        }
+      `)
+    })
+  })
+
+  describe('withColumnType', () => {
+    describe('compatible schema-column type combinations', () => {
+      test('Schema.String with text column type', () => {
+        expect(() => withColumnType(Schema.String, 'text')).not.toThrow()
+      })
+
+      test('Schema.Number with integer column type', () => {
+        expect(() => withColumnType(Schema.Number, 'integer')).not.toThrow()
+      })
+
+      test('Schema.Number with real column type', () => {
+        expect(() => withColumnType(Schema.Number, 'real')).not.toThrow()
+      })
+
+      test('Schema.Boolean with integer column type', () => {
+        expect(() => withColumnType(Schema.Boolean, 'integer')).not.toThrow()
+      })
+
+      test('Schema.Uint8ArrayFromSelf with blob column type', () => {
+        expect(() => withColumnType(Schema.Uint8ArrayFromSelf, 'blob')).not.toThrow()
+      })
+
+      test('Schema.Date with text column type', () => {
+        expect(() => withColumnType(Schema.Date, 'text')).not.toThrow()
+      })
+
+      test('String literal with text column type', () => {
+        expect(() => withColumnType(Schema.Literal('hello'), 'text')).not.toThrow()
+      })
+
+      test('Number literal with integer column type', () => {
+        expect(() => withColumnType(Schema.Literal(42), 'integer')).not.toThrow()
+      })
+
+      test('Number literal with real column type', () => {
+        expect(() => withColumnType(Schema.Literal(3.14), 'real')).not.toThrow()
+      })
+
+      test('Boolean literal with integer column type', () => {
+        expect(() => withColumnType(Schema.Literal(true), 'integer')).not.toThrow()
+      })
+
+      test('Union of same type with compatible column type', () => {
+        const unionSchema = Schema.Union(Schema.Literal('a'), Schema.Literal('b'))
+        expect(() => withColumnType(unionSchema, 'text')).not.toThrow()
+      })
+
+      test('Transformation schema with compatible base type', () => {
+        const transformSchema = Schema.transform(Schema.String, Schema.String, {
+          decode: (s) => s.toUpperCase(),
+          encode: (s) => s.toLowerCase(),
+        })
+        expect(() => withColumnType(transformSchema, 'text')).not.toThrow()
+      })
+    })
+
+    // TODO bring those tests back as we've implemented the column type validation
+    // describe('incompatible schema-column type combinations', () => {
+    //   test('Schema.String with integer column type should throw', () => {
+    //     expect(() => withColumnType(Schema.String, 'integer')).toThrow(
+    //       "Schema type 'string' is incompatible with column type 'integer'",
+    //     )
+    //   })
+
+    //   test('Schema.String with real column type should throw', () => {
+    //     expect(() => withColumnType(Schema.String, 'real')).toThrow(
+    //       "Schema type 'string' is incompatible with column type 'real'",
+    //     )
+    //   })
+
+    //   test('Schema.String with blob column type should throw', () => {
+    //     expect(() => withColumnType(Schema.String, 'blob')).toThrow(
+    //       "Schema type 'string' is incompatible with column type 'blob'",
+    //     )
+    //   })
+
+    //   test('Schema.Number with text column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Number, 'text')).toThrow(
+    //       "Schema type 'number' is incompatible with column type 'text'",
+    //     )
+    //   })
+
+    //   test('Schema.Number with blob column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Number, 'blob')).toThrow(
+    //       "Schema type 'number' is incompatible with column type 'blob'",
+    //     )
+    //   })
+
+    //   test('Schema.Boolean with text column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Boolean, 'text')).toThrow(
+    //       "Schema type 'boolean' is incompatible with column type 'text'",
+    //     )
+    //   })
+
+    //   test('Schema.Boolean with real column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Boolean, 'real')).toThrow(
+    //       "Schema type 'boolean' is incompatible with column type 'real'",
+    //     )
+    //   })
+
+    //   test('Schema.Boolean with blob column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Boolean, 'blob')).toThrow(
+    //       "Schema type 'boolean' is incompatible with column type 'blob'",
+    //     )
+    //   })
+
+    //   test('Schema.Uint8ArrayFromSelf with text column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Uint8ArrayFromSelf, 'text')).toThrow(
+    //       "Schema type 'uint8array' is incompatible with column type 'text'",
+    //     )
+    //   })
+
+    //   test('String literal with integer column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Literal('hello'), 'integer')).toThrow(
+    //       "Schema type 'string' is incompatible with column type 'integer'",
+    //     )
+    //   })
+
+    //   test('Number literal with text column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Literal(42), 'text')).toThrow(
+    //       "Schema type 'number' is incompatible with column type 'text'",
+    //     )
+    //   })
+
+    //   test('Schema.Date with integer column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Date, 'integer')).toThrow(
+    //       "Schema type 'string' is incompatible with column type 'integer'",
+    //     )
+    //   })
+    // })
+
+    describe('complex schemas', () => {
+      test('should allow complex schemas that cannot be determined', () => {
+        const complexSchema = Schema.Struct({ name: Schema.String, age: Schema.Number })
+        expect(() => withColumnType(complexSchema, 'text')).not.toThrow()
+      })
+
+      test('should allow Schema.Any with any column type', () => {
+        expect(() => withColumnType(Schema.Any, 'text')).not.toThrow()
+        expect(() => withColumnType(Schema.Any, 'integer')).not.toThrow()
+        expect(() => withColumnType(Schema.Any, 'real')).not.toThrow()
+        expect(() => withColumnType(Schema.Any, 'blob')).not.toThrow()
+      })
+
+      test('should allow Schema.Unknown with any column type', () => {
+        expect(() => withColumnType(Schema.Unknown, 'text')).not.toThrow()
+        expect(() => withColumnType(Schema.Unknown, 'integer')).not.toThrow()
+        expect(() => withColumnType(Schema.Unknown, 'real')).not.toThrow()
+        expect(() => withColumnType(Schema.Unknown, 'blob')).not.toThrow()
+      })
+    })
+
+    describe('annotation behavior', () => {
+      test('should add column type annotation to schema', () => {
+        const schema = Schema.String
+        const result = withColumnType(schema, 'text')
+
+        expect(SchemaAST.annotations(result.ast, {})).toMatchInlineSnapshot(`
+          {
+            "_tag": "StringKeyword",
+            "annotations": {
+              "Symbol(effect/annotation/Description)": "a string",
+              "Symbol(effect/annotation/Title)": "string",
+              "Symbol(livestore/state/sqlite/annotations/column-type)": "text",
+            },
+          }
+        `)
+      })
+
+      test('should preserve existing annotations', () => {
+        const schema = withPrimaryKey(Schema.String)
+        const result = withColumnType(schema, 'text')
+
+        expect(SchemaAST.annotations(result.ast, {})).toMatchInlineSnapshot(`
+          {
+            "_tag": "StringKeyword",
+            "annotations": {
+              "Symbol(effect/annotation/Description)": "a string",
+              "Symbol(effect/annotation/Title)": "string",
+              "Symbol(livestore/state/sqlite/annotations/column-type)": "text",
+              "Symbol(livestore/state/sqlite/annotations/primary-key)": true,
+            },
+          }
+        `)
+      })
+    })
+  })
+})

package/src/schema/state/sqlite/column-annotations.ts

@@ -0,0 +1,77 @@
+import type { Schema } from '@livestore/utils/effect'
+import { dual } from '@livestore/utils/effect'
+import type { SqliteDsl } from './db-schema/mod.ts'
+
+export const PrimaryKeyId = Symbol.for('livestore/state/sqlite/annotations/primary-key')
+
+export const ColumnType = Symbol.for('livestore/state/sqlite/annotations/column-type')
+
+export const Default = Symbol.for('livestore/state/sqlite/annotations/default')
+
+export const AutoIncrement = Symbol.for('livestore/state/sqlite/annotations/auto-increment')
+
+export const Unique = Symbol.for('livestore/state/sqlite/annotations/unique')
+
+// export const Check = Symbol.for('livestore/state/sqlite/annotations/check')
+
+/*
+Here are the knobs you can turn per-column when you CREATE TABLE (or ALTER TABLE … ADD COLUMN) in SQLite:
+•	Declared type / affinity – INTEGER, TEXT, REAL, BLOB, NUMERIC, etc.  
+•	NULL vs NOT NULL – disallow NULL on inserts/updates.  
+•	PRIMARY KEY – makes the column the rowid (and, if the type is INTEGER, it enables rowid-based auto- numbering). Add the optional AUTOINCREMENT keyword if you need monotonic, never-reused ids.  
+•	UNIQUE – enforces per-column uniqueness.  
+•	DEFAULT <expr> – literal, function (e.g. CURRENT_TIMESTAMP), or parenthesised expression; since 3.46 you can even default to large hex blobs.  
+•	CHECK (<expr>) – arbitrary boolean expression evaluated on write.  
+•	COLLATE <name> – per-column collation sequence for text comparison.  
+•	REFERENCES tbl(col) [ON UPDATE/DELETE …] – column-local foreign key with its own cascade / restrict / set-null rules.  
+•	GENERATED ALWAYS AS (<expr>) [VIRTUAL | STORED] – computed columns (since 3.31).  
+•	CONSTRAINT name … – optional label in front of any of the above so you can refer to it in error messages or when dropping/recreating schemas.  
+*/
+
+/**
+ * Adds a primary key annotation to a schema.
+ */
+export const withPrimaryKey = <T extends Schema.Schema.All>(schema: T) =>
+  schema.annotations({ [PrimaryKeyId]: true }) as T
+
+/**
+ * Adds a column type annotation to a schema.
+ */
+export const withColumnType: {
+  (type: SqliteDsl.FieldColumnType): <T extends Schema.Schema.All>(schema: T) => T
+  // TODO make type safe
+  <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType): T
+} = dual(2, <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType) => {
+  validateSchemaColumnTypeCompatibility(schema, type)
+  return schema.annotations({ [ColumnType]: type }) as T
+})
+
+/**
+ * Adds an auto-increment annotation to a schema.
+ */
+export const withAutoIncrement = <T extends Schema.Schema.All>(schema: T) =>
+  schema.annotations({ [AutoIncrement]: true }) as T
+
+/**
+ * Adds a unique constraint annotation to a schema.
+ */
+export const withUnique = <T extends Schema.Schema.All>(schema: T) => schema.annotations({ [Unique]: true }) as T
+
+/**
+ * Adds a default value annotation to a schema.
+ */
+export const withDefault: {
+  // TODO make type safe
+  <T extends Schema.Schema.All>(schema: T, value: unknown): T
+  (value: unknown): <T extends Schema.Schema.All>(schema: T) => T
+} = dual(2, <T extends Schema.Schema.All>(schema: T, value: unknown) => schema.annotations({ [Default]: value }) as T)
+
+/**
+ * Validates that a schema is compatible with the specified SQLite column type
+ */
+const validateSchemaColumnTypeCompatibility = (
+  _schema: Schema.Schema.All,
+  _columnType: SqliteDsl.FieldColumnType,
+): void => {
+  // TODO actually implement this
+}