@livestore/common 0.4.0 → 0.5.0-dev.0

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

@@ -1,8 +1,7 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import type { Option, Types } from '@livestore/utils/effect'
-import { Schema } from '@livestore/utils/effect'
+import { type Option, type Types, Schema, SchemaGetter, Struct } from '@livestore/utils/effect'
 
-import { SessionIdSymbol } from '../../../adapter-types.ts'
+import { SessionIdSymbol } from '../../../session-id-symbol.ts'
 import { sql } from '../../../util.ts'
 import type { EventDef, Materializer } from '../../EventDef/mod.ts'
 import { defineEvent, defineMaterializer } from '../../EventDef/mod.ts'
@@ -47,7 +46,7 @@ export const clientDocument = <
   ...inputOptions
 }: {
   name: TName
-  schema: Schema.Schema<TType, TEncoded>
+  schema: Schema.Codec<TType, TEncoded>
 } & TOptions): ClientDocumentTableDef<
   TName,
   TType,
@@ -61,6 +60,7 @@ export const clientDocument = <
       value: inputOptions.default.value,
     },
   } satisfies ClientDocumentTableOptions<TType>
+  const canPartialSet = options.partialSet === true && Schema.getResolvedPropertySignatures(valueSchema).length > 0
 
   // Column needs optimistic schema to read historical data formats
   const optimisticColumnSchema = createOptimisticEventSchema({
@@ -83,7 +83,7 @@ export const clientDocument = <
     name,
     valueSchema,
     defaultValue: options.default.value,
-    partialSet: options.partialSet,
+    partialSet: canPartialSet,
   })
 
   const setEventDef = (...args: any[]) => {
@@ -95,8 +95,8 @@ export const clientDocument = <
   Object.defineProperty(setEventDef, 'schema', {
     value: Schema.Struct({
       id: Schema.String,
-      value: options.partialSet === true ? Schema.partial(valueSchema) : valueSchema,
-    }).annotations({ title: `${name}Set:Args` }),
+      value: canPartialSet === true ? partialStructSchema(valueSchema) : valueSchema,
+    }).annotate({ title: `${name}Set:Args` }) as Schema.Codec<any, any>,
   })
   Object.defineProperty(setEventDef, 'options', {
     value: { derived: true, clientOnly: true, facts: undefined, deprecated: undefined },
@@ -158,6 +158,19 @@ export const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T
   }, {} as any)
 }
 
+const partialStructSchema = (schema: Schema.Codec<any, any>): Schema.Codec<any, any> =>
+  (schema as unknown as Schema.Struct<Schema.Struct.Fields>).mapFields(
+    Struct.map(Schema.optional),
+  ) as unknown as Schema.Codec<any, any>
+
+const pickStructSchema = (
+  schema: Schema.Codec<any, any>,
+  keys: ReadonlyArray<string>,
+): Schema.Codec<Record<string, unknown>, Record<string, unknown>> =>
+  (schema as unknown as Schema.Struct<Schema.Struct.Fields>).mapFields(
+    Struct.pick(keys as readonly any[]),
+  ) as unknown as Schema.Codec<Record<string, unknown>, Record<string, unknown>>
+
 /**
  * Creates an optimistic schema that accepts historical event formats
  * and transforms them to the current schema, preserving data and intent.
@@ -182,88 +195,90 @@ export const createOptimisticEventSchema = ({
   defaultValue,
   partialSet,
 }: {
-  valueSchema: Schema.Schema<any, any>
+  valueSchema: Schema.Codec<any, any>
   defaultValue: any
   partialSet: boolean
-}) => {
-  const targetSchema = partialSet === true ? Schema.partial(valueSchema) : valueSchema
+}): Schema.Codec<any, unknown> => {
+  const canPartialSet = partialSet === true && Schema.getResolvedPropertySignatures(valueSchema).length > 0
+  const targetSchema = canPartialSet === true ? partialStructSchema(valueSchema) : valueSchema
   // The transform decode must yield values in the target schema's ENCODED shape.
   // This keeps JSON columns consistent when Encoded != Type (e.g. Option).
   const encodeTarget = Schema.encodeSync(targetSchema)
 
-  return Schema.transform(
-    Schema.Unknown, // Accept any historical event structure
-    targetSchema, // Output current schema
-    {
-      decode: (eventValue) => {
-        // Try direct decode first (for current schema events)
-        try {
-          const decoded = Schema.decodeUnknownSync(targetSchema)(eventValue)
-          // Re-encode so downstream parseJson/column decoding sees encoded values.
-          return encodeTarget(decoded)
-        } catch {
-          // Optimistic decoding for historical events
-
-          // Handle null/undefined/non-object cases
-          if (typeof eventValue !== 'object' || eventValue === null) {
-            console.warn(
-              `Client document: Non-object event value, using ${partialSet === true ? 'empty partial' : 'defaults'}`,
-            )
-            return encodeTarget(partialSet === true ? {} : defaultValue)
-          }
+  return Schema.Unknown.pipe(
+    Schema.decodeTo(
+      targetSchema, // Output current schema
+      {
+        decode: SchemaGetter.transform((eventValue) => {
+          // Try direct decode first (for current schema events)
+          try {
+            const decoded = Schema.decodeUnknownSync(targetSchema)(eventValue)
+            // Re-encode so downstream parseJson/column decoding sees encoded values.
+            return encodeTarget(decoded)
+          } catch {
+            // Optimistic decoding for historical events
+
+            // Handle null/undefined/non-object cases
+            if (typeof eventValue !== 'object' || eventValue === null) {
+              console.warn(
+                `Client document: Non-object event value, using ${canPartialSet === true ? 'empty partial' : 'defaults'}`,
+              )
+              return encodeTarget(canPartialSet === true ? {} : defaultValue)
+            }
 
-          if (partialSet === true) {
-            // For partial sets: only preserve fields that exist in new schema
-            const partialResult: Record<string, unknown> = {}
-            let hasValidFields = false
+            if (canPartialSet === true) {
+              // For partial sets: only preserve fields that exist in new schema
+              const partialResult: Record<string, unknown> = {}
+              let hasValidFields = false
+
+              for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+                if (key in defaultValue) {
+                  partialResult[key] = value
+                  hasValidFields = true
+                }
+                // Drop fields that don't exist in new schema
+              }
 
-            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
-              if (key in defaultValue) {
-                partialResult[key] = value
-                hasValidFields = true
+              if (hasValidFields === true) {
+                try {
+                  const decoded = Schema.decodeUnknownSync(targetSchema)(partialResult)
+                  return encodeTarget(decoded)
+                } catch {
+                  // Even filtered fields don't match schema
+                  console.warn('Client document: Partial fields incompatible, returning empty partial')
+                  return encodeTarget({})
+                }
+              }
+              return encodeTarget({})
+            } else {
+              // Full set: merge old data with new defaults
+              const merged: Record<string, unknown> = { ...defaultValue }
+
+              // Override defaults with valid fields from old event
+              for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+                if (key in defaultValue) {
+                  merged[key] = value
+                }
+                // Drop fields that don't exist in new schema
               }
-              // Drop fields that don't exist in new schema
-            }
 
-            if (hasValidFields === true) {
+              // Try to decode the merged value
               try {
-                const decoded = Schema.decodeUnknownSync(targetSchema)(partialResult)
+                const decoded = Schema.decodeUnknownSync(valueSchema)(merged)
                 return encodeTarget(decoded)
               } catch {
-                // Even filtered fields don't match schema
-                console.warn('Client document: Partial fields incompatible, returning empty partial')
-                return encodeTarget({})
-              }
-            }
-            return encodeTarget({})
-          } else {
-            // Full set: merge old data with new defaults
-            const merged: Record<string, unknown> = { ...defaultValue }
-
-            // Override defaults with valid fields from old event
-            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
-              if (key in defaultValue) {
-                merged[key] = value
+                // Merged value still doesn't match (e.g., type changes)
+                // Fall back to pure defaults
+                console.warn('Client document: Could not preserve event data, using defaults')
+                return encodeTarget(defaultValue)
               }
-              // Drop fields that don't exist in new schema
-            }
-
-            // Try to decode the merged value
-            try {
-              const decoded = Schema.decodeUnknownSync(valueSchema)(merged)
-              return encodeTarget(decoded)
-            } catch {
-              // Merged value still doesn't match (e.g., type changes)
-              // Fall back to pure defaults
-              console.warn('Client document: Could not preserve event data, using defaults')
-              return encodeTarget(defaultValue)
             }
           }
-        }
+        }),
+        encode: SchemaGetter.passthroughSubtype(),
       },
-      encode: (value) => value, // Pass-through for encoding
-    },
-  )
+    ),
+  ) as Schema.Codec<any, unknown>
 }
 
 export const deriveEventAndMaterializer = ({
@@ -273,16 +288,16 @@ export const deriveEventAndMaterializer = ({
   partialSet,
 }: {
   name: string
-  valueSchema: Schema.Schema<any, any>
+  valueSchema: Schema.Codec<any, any>
   defaultValue: any
   partialSet: boolean
 }) => {
   const derivedSetEventDef = defineEvent({
     name: `${name}Set`,
     schema: Schema.Struct({
-      id: Schema.Union(Schema.String, Schema.UniqueSymbolFromSelf(SessionIdSymbol)),
+      id: Schema.Union([Schema.String, Schema.UniqueSymbol(SessionIdSymbol)]),
       value: createOptimisticEventSchema({ valueSchema, defaultValue, partialSet }),
-    }).annotations({ title: `${name}Set:Args` }),
+    }).annotate({ title: `${name}Set:Args` }),
     clientOnly: true,
     derived: true,
   })
@@ -295,7 +310,7 @@ export const deriveEventAndMaterializer = ({
     // Override the full value if it's not an object or no partial set is allowed
     const schemaProps = Schema.getResolvedPropertySignatures(valueSchema)
     if (schemaProps.length === 0 || partialSet === false) {
-      const valueColJsonSchema = Schema.parseJson(valueSchema)
+      const valueColJsonSchema = Schema.fromJsonString(valueSchema) as Schema.Codec<any, string>
       const encodedInsertValue = Schema.encodeSyncDebug(valueColJsonSchema)(value ?? defaultValue)
       const encodedUpdateValue = Schema.encodeSyncDebug(valueColJsonSchema)(value)
 
@@ -305,7 +320,7 @@ export const deriveEventAndMaterializer = ({
         writeTables: new Set([name]),
       }
     } else {
-      const valueColJsonSchema = Schema.parseJson(Schema.partial(valueSchema))
+      const valueColJsonSchema = Schema.fromJsonString(partialStructSchema(valueSchema)) as Schema.Codec<any, string>
 
       const encodedInsertValue = Schema.encodeSyncDebug(valueColJsonSchema)(mergeDefaultValues(defaultValue, value))
 
@@ -313,7 +328,7 @@ export const deriveEventAndMaterializer = ({
       const setBindValues: unknown[] = []
 
       const keys = Object.keys(value)
-      const partialUpdateSchema = valueSchema.pipe(Schema.pick(...keys))
+      const partialUpdateSchema = pickStructSchema(valueSchema, keys)
       const encodedPartialUpdate = Schema.encodeSyncDebug(partialUpdateSchema)(value)
 
       for (const key in encodedPartialUpdate) {
@@ -525,7 +540,7 @@ export namespace ClientDocumentTableDef {
      */
     readonly set: SetEventDefLike<TName, TType, TOptions>
     readonly Value: TType
-    readonly valueSchema: Schema.Schema<TType, TEncoded>
+    readonly valueSchema: Schema.Codec<TType, TEncoded>
     readonly default: TOptions['default']
     readonly [ClientDocumentTableDefSymbol]: {
       readonly options: TOptions
@@ -562,7 +577,7 @@ export namespace ClientDocumentTableDef {
         id?: string | SessionIdSymbol,
       ) => { name: `${TName}Set`; args: { id: string; value: TType } }) & {
     readonly name: `${TName}Set`
-    readonly schema: Schema.Schema<any>
+    readonly schema: Schema.Codec<any, any>
     readonly Event: {
       readonly name: `${TName}Set`
       readonly args: { id: string; value: TType }

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

@@ -1,8 +1,8 @@
 import { describe, expect, test } from 'vitest'
 
-import { Schema, SchemaAST } from '@livestore/utils/effect'
+import { Schema, SchemaAST, SchemaTransformation } from '@livestore/utils/effect'
 
-import { withColumnType, withPrimaryKey } from './column-annotations.ts'
+import { ColumnType, PrimaryKeyId, withColumnType, withPrimaryKey } from './column-annotations.ts'
 
 describe.concurrent('annotations', () => {
   describe('withPrimaryKey', () => {
@@ -10,16 +10,8 @@ describe.concurrent('annotations', () => {
       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,
-          },
-        }
-      `)
+      expect(SchemaAST.isString(result.ast)).toBe(true)
+      expect(Schema.resolveAnnotations(result)?.[PrimaryKeyId]).toBe(true)
     })
   })
 
@@ -30,19 +22,19 @@ describe.concurrent('annotations', () => {
       })
 
       test('Schema.Number with integer column type', () => {
-        expect(() => withColumnType(Schema.Number, 'integer')).not.toThrow()
+        expect(() => withColumnType(Schema.Finite, 'integer')).not.toThrow()
       })
 
       test('Schema.Number with real column type', () => {
-        expect(() => withColumnType(Schema.Number, 'real')).not.toThrow()
+        expect(() => withColumnType(Schema.Finite, '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.Uint8Array with blob column type', () => {
+        expect(() => withColumnType(Schema.Uint8Array, 'blob')).not.toThrow()
       })
 
       test('Schema.Date with text column type', () => {
@@ -66,15 +58,20 @@ describe.concurrent('annotations', () => {
       })
 
       test('Union of same type with compatible column type', () => {
-        const unionSchema = Schema.Literal('a', 'b')
+        const unionSchema = Schema.Literals(['a', '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(),
-        })
+        const transformSchema = Schema.String.pipe(
+          Schema.decodeTo(
+            Schema.String,
+            SchemaTransformation.transform({
+              decode: (s) => s.toUpperCase(),
+              encode: (s) => s.toLowerCase(),
+            }),
+          ),
+        )
         expect(() => withColumnType(transformSchema, 'text')).not.toThrow()
       })
     })
@@ -129,8 +126,8 @@ describe.concurrent('annotations', () => {
     //     )
     //   })
 
-    //   test('Schema.Uint8ArrayFromSelf with text column type should throw', () => {
-    //     expect(() => withColumnType(Schema.Uint8ArrayFromSelf, 'text')).toThrow(
+    //   test('Schema.Uint8Array with text column type should throw', () => {
+    //     expect(() => withColumnType(Schema.Uint8Array, 'text')).toThrow(
     //       "Schema type 'uint8array' is incompatible with column type 'text'",
     //     )
     //   })
@@ -156,7 +153,7 @@ describe.concurrent('annotations', () => {
 
     describe('complex schemas', () => {
       test('should allow complex schemas that cannot be determined', () => {
-        const complexSchema = Schema.Struct({ name: Schema.String, age: Schema.Number })
+        const complexSchema = Schema.Struct({ name: Schema.String, age: Schema.Finite })
         expect(() => withColumnType(complexSchema, 'text')).not.toThrow()
       })
 
@@ -180,33 +177,17 @@ describe.concurrent('annotations', () => {
         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",
-            },
-          }
-        `)
+        expect(SchemaAST.isString(result.ast)).toBe(true)
+        expect(Schema.resolveAnnotations(result)?.[ColumnType]).toBe('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,
-            },
-          }
-        `)
+        expect(SchemaAST.isString(result.ast)).toBe(true)
+        expect(Schema.resolveAnnotations(result)?.[ColumnType]).toBe('text')
+        expect(Schema.resolveAnnotations(result)?.[PrimaryKeyId]).toBe(true)
       })
     })
   })

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

@@ -1,19 +1,18 @@
-import type { Schema } from '@livestore/utils/effect'
-import { dual, Option, SchemaAST } from '@livestore/utils/effect'
+import { type Schema, Function, SchemaAST } 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 PrimaryKeyId = 'livestore/state/sqlite/annotations/primary-key'
 
-export const ColumnType = Symbol.for('livestore/state/sqlite/annotations/column-type')
+export const ColumnType = 'livestore/state/sqlite/annotations/column-type'
 
-export const Default = Symbol.for('livestore/state/sqlite/annotations/default')
+export const Default = 'livestore/state/sqlite/annotations/default'
 
-export const AutoIncrement = Symbol.for('livestore/state/sqlite/annotations/auto-increment')
+export const AutoIncrement = 'livestore/state/sqlite/annotations/auto-increment'
 
-export const Unique = Symbol.for('livestore/state/sqlite/annotations/unique')
+export const Unique = 'livestore/state/sqlite/annotations/unique'
 
-// export const Check = Symbol.for('livestore/state/sqlite/annotations/check')
+// export const Check = '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:
@@ -26,23 +25,22 @@ Here are the knobs you can turn per-column when you CREATE TABLE (or ALTER TABLE
 •	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.  
+•	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) =>
-  applyAnnotations(schema, { [PrimaryKeyId]: true })
+export const withPrimaryKey = <T extends Schema.Top>(schema: T) => applyAnnotations(schema, { [PrimaryKeyId]: true })
 
 /**
  * Adds a column type annotation to a schema.
  */
 export const withColumnType: {
-  (type: SqliteDsl.FieldColumnType): <T extends Schema.Schema.All>(schema: T) => T
+  (type: SqliteDsl.FieldColumnType): <T extends Schema.Top>(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) => {
+  <T extends Schema.Top>(schema: T, type: SqliteDsl.FieldColumnType): T
+} = Function.dual(2, <T extends Schema.Top>(schema: T, type: SqliteDsl.FieldColumnType) => {
   validateSchemaColumnTypeCompatibility(schema, type)
   return applyAnnotations(schema, { [ColumnType]: type })
 })
@@ -50,39 +48,37 @@ export const withColumnType: {
 /**
  * Adds an auto-increment annotation to a schema.
  */
-export const withAutoIncrement = <T extends Schema.Schema.All>(schema: T) =>
+export const withAutoIncrement = <T extends Schema.Top>(schema: T) =>
   applyAnnotations(schema, { [AutoIncrement]: true })
 
 /**
  * Adds a unique constraint annotation to a schema.
  */
-export const withUnique = <T extends Schema.Schema.All>(schema: T) => applyAnnotations(schema, { [Unique]: true })
+export const withUnique = <T extends Schema.Top>(schema: T) => applyAnnotations(schema, { [Unique]: true })
 
 /**
  * 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) => applyAnnotations(schema, { [Default]: value }))
+  <T extends Schema.Top>(schema: T, value: unknown): T
+  (value: unknown): <T extends Schema.Top>(schema: T) => T
+} = Function.dual(2, <T extends Schema.Top>(schema: T, value: unknown) =>
+  applyAnnotations(schema, { [Default]: value }),
+)
 
 /**
  * Validates that a schema is compatible with the specified SQLite column type
  */
-const validateSchemaColumnTypeCompatibility = (
-  _schema: Schema.Schema.All,
-  _columnType: SqliteDsl.FieldColumnType,
-): void => {
+const validateSchemaColumnTypeCompatibility = (_schema: Schema.Top, _columnType: SqliteDsl.FieldColumnType): void => {
   // TODO actually implement this
 }
 
-const applyAnnotations = <T extends Schema.Schema.All>(schema: T, overrides: Record<PropertyKey, unknown>): T => {
-  const identifier = SchemaAST.getIdentifierAnnotation(schema.ast)
-  const shouldPreserveIdentifier = Option.isSome(identifier) && !(SchemaAST.IdentifierAnnotationId in overrides)
-  const annotations: Record<PropertyKey, unknown> = shouldPreserveIdentifier === true
-    ? { ...overrides, [SchemaAST.IdentifierAnnotationId]: identifier.value }
-    : overrides
+const applyAnnotations = <T extends Schema.Top>(schema: T, overrides: Record<string, unknown>): T => {
+  const identifier = SchemaAST.resolveIdentifier(schema.ast)
+  const shouldPreserveIdentifier = identifier !== undefined && !('identifier' in overrides)
+  const annotations: Record<string, unknown> =
+    shouldPreserveIdentifier === true ? { ...overrides, identifier } : overrides
 
-  return schema.annotations(annotations) as T
+  return schema.annotate(annotations) as T
 }