@livestore/common 0.4.0-dev.12 → 0.4.0-dev.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/.tsbuildinfo +1 -1
  2. package/dist/devtools/devtools-messages-client-session.d.ts +21 -21
  3. package/dist/devtools/devtools-messages-common.d.ts +6 -6
  4. package/dist/devtools/devtools-messages-leader.d.ts +24 -24
  5. package/dist/index.d.ts +1 -1
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/leader-thread/eventlog.js +2 -1
  10. package/dist/leader-thread/eventlog.js.map +1 -1
  11. package/dist/schema/mod.d.ts +1 -1
  12. package/dist/schema/mod.d.ts.map +1 -1
  13. package/dist/schema/mod.js +1 -1
  14. package/dist/schema/mod.js.map +1 -1
  15. package/dist/schema/schema.js +1 -1
  16. package/dist/schema/schema.js.map +1 -1
  17. package/dist/schema/state/sqlite/column-def.js +9 -0
  18. package/dist/schema/state/sqlite/column-def.js.map +1 -1
  19. package/dist/schema/state/sqlite/column-def.test.js +10 -0
  20. package/dist/schema/state/sqlite/column-def.test.js.map +1 -1
  21. package/dist/schema/state/sqlite/mod.js +1 -1
  22. package/dist/schema/state/sqlite/mod.js.map +1 -1
  23. package/dist/schema/state/sqlite/system-tables/eventlog-tables.d.ts +547 -0
  24. package/dist/schema/state/sqlite/system-tables/eventlog-tables.d.ts.map +1 -0
  25. package/dist/schema/state/sqlite/system-tables/eventlog-tables.js +54 -0
  26. package/dist/schema/state/sqlite/system-tables/eventlog-tables.js.map +1 -0
  27. package/dist/schema/state/sqlite/system-tables/mod.d.ts +3 -0
  28. package/dist/schema/state/sqlite/system-tables/mod.d.ts.map +1 -0
  29. package/dist/schema/state/sqlite/system-tables/mod.js +3 -0
  30. package/dist/schema/state/sqlite/system-tables/mod.js.map +1 -0
  31. package/dist/schema/state/sqlite/system-tables/state-tables.d.ts +456 -0
  32. package/dist/schema/state/sqlite/system-tables/state-tables.d.ts.map +1 -0
  33. package/dist/schema/state/sqlite/system-tables/state-tables.js +55 -0
  34. package/dist/schema/state/sqlite/system-tables/state-tables.js.map +1 -0
  35. package/dist/schema-management/migrations.d.ts +30 -0
  36. package/dist/schema-management/migrations.d.ts.map +1 -1
  37. package/dist/schema-management/migrations.js +31 -1
  38. package/dist/schema-management/migrations.js.map +1 -1
  39. package/dist/version.d.ts +15 -5
  40. package/dist/version.d.ts.map +1 -1
  41. package/dist/version.js +15 -5
  42. package/dist/version.js.map +1 -1
  43. package/package.json +4 -4
  44. package/src/index.ts +1 -1
  45. package/src/leader-thread/eventlog.ts +2 -2
  46. package/src/schema/mod.ts +1 -1
  47. package/src/schema/schema.ts +1 -1
  48. package/src/schema/state/sqlite/column-def.test.ts +13 -0
  49. package/src/schema/state/sqlite/column-def.ts +16 -0
  50. package/src/schema/state/sqlite/mod.ts +1 -1
  51. package/src/schema/state/sqlite/system-tables/eventlog-tables.ts +64 -0
  52. package/src/schema/state/sqlite/system-tables/mod.ts +2 -0
  53. package/src/schema/state/sqlite/system-tables/state-tables.ts +69 -0
  54. package/src/schema-management/migrations.ts +33 -2
  55. package/src/version.ts +15 -5
  56. package/src/schema/state/sqlite/system-tables.ts +0 -106
package/dist/version.js CHANGED
@@ -1,13 +1,23 @@
1
1
  // TODO bring back when Expo and Playwright supports `with` imports
2
2
  // import packageJson from '../package.json' with { type: 'json' }
3
3
  // export const liveStoreVersion = packageJson.version
4
- export const liveStoreVersion = '0.4.0-dev.12';
4
+ export const liveStoreVersion = '0.4.0-dev.13';
5
5
  /**
6
- * This version number is incremented whenever the internal storage format changes in a breaking way.
7
- * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
6
+ * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.
8
7
  *
9
- * While LiveStore is in beta, this might happen more frequently.
10
- * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
8
+ * Used to generate database file names (e.g., `eventlog@6.db`, `state@6.db`) across all client adapters.
9
+ *
10
+ * Bump required when:
11
+ * - Modifying eventlog system tables (eventlogMetaTable, syncStatusTable) in schema/state/sqlite/system-tables/eventlog-tables.ts
12
+ * - Changing columns, types, constraints, or indexes in eventlog tables
13
+ *
14
+ * Bump NOT required when:
15
+ * - Modifying STATE table schemas (auto-migrated via hash-based detection and rebuilt from eventlog)
16
+ * - Changing query patterns or client-side implementation details
17
+ *
18
+ * ⚠️ CRITICAL: Eventlog changes without bumping this version cause permanent data loss!
19
+ *
20
+ * Impact: Version changes trigger a "soft reset" - old data becomes inaccessible but remains on disk.
11
21
  */
12
22
  export const liveStoreStorageFormatVersion = 6;
13
23
  //# sourceMappingURL=version.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAuB,CAAA;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAuB,CAAA;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livestore/common",
3
- "version": "0.4.0-dev.12",
3
+ "version": "0.4.0-dev.13",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "exports": {
@@ -15,12 +15,12 @@
15
15
  },
16
16
  "dependencies": {
17
17
  "@opentelemetry/api": "1.9.0",
18
- "@livestore/utils": "0.4.0-dev.12",
19
- "@livestore/webmesh": "0.4.0-dev.12"
18
+ "@livestore/utils": "0.4.0-dev.13",
19
+ "@livestore/webmesh": "0.4.0-dev.13"
20
20
  },
21
21
  "devDependencies": {
22
22
  "vitest": "3.2.4",
23
- "@livestore/utils-dev": "0.4.0-dev.12"
23
+ "@livestore/utils-dev": "0.4.0-dev.13"
24
24
  },
25
25
  "files": [
26
26
  "package.json",
package/src/index.ts CHANGED
@@ -7,7 +7,7 @@ export * from './materializer-helper.ts'
7
7
  export * from './otel.ts'
8
8
  export * from './rematerialize-from-eventlog.ts'
9
9
  export * from './schema/state/sqlite/query-builder/mod.ts'
10
- export * from './schema/state/sqlite/system-tables.ts'
10
+ export * from './schema/state/sqlite/system-tables/mod.ts'
11
11
  export * from './schema-management/migrations.ts'
12
12
  export * as SqliteDbHelper from './sqlite-db-helper.ts'
13
13
  export * from './sync/index.ts'
@@ -9,8 +9,8 @@ import {
9
9
  eventlogMetaTable,
10
10
  eventlogSystemTables,
11
11
  SYNC_STATUS_TABLE,
12
- sessionChangesetMetaTable,
13
- } from '../schema/state/sqlite/system-tables.ts'
12
+ } from '../schema/state/sqlite/system-tables/eventlog-tables.ts'
13
+ import { sessionChangesetMetaTable } from '../schema/state/sqlite/system-tables/state-tables.ts'
14
14
  import { migrateTable } from '../schema-management/migrations.ts'
15
15
  import { insertRow, updateRows } from '../sql-queries/sql-queries.ts'
16
16
  import type { PreparedBindValues } from '../util.ts'
package/src/schema/mod.ts CHANGED
@@ -6,6 +6,6 @@ export * from './schema.ts'
6
6
  export * as State from './state/mod.ts'
7
7
  export { SqliteAst, SqliteDsl } from './state/sqlite/db-schema/mod.ts'
8
8
  export * from './state/sqlite/schema-helpers.ts'
9
- export * as SystemTables from './state/sqlite/system-tables.ts'
9
+ export * as SystemTables from './state/sqlite/system-tables/mod.ts'
10
10
  export type { UnknownEvents } from './unknown-events.ts'
11
11
  export { normalizeUnknownEventHandling, resolveEventDef } from './unknown-events.ts'
@@ -4,7 +4,7 @@ import type { MigrationOptions } from '../adapter-types.ts'
4
4
  import type { EventDef, EventDefRecord, Materializer } from './EventDef.ts'
5
5
  import { tableIsClientDocumentTable } from './state/sqlite/client-document-def.ts'
6
6
  import type { SqliteDsl } from './state/sqlite/db-schema/mod.ts'
7
- import { stateSystemTables } from './state/sqlite/system-tables.ts'
7
+ import { stateSystemTables } from './state/sqlite/system-tables/state-tables.ts'
8
8
  import type { TableDef } from './state/sqlite/table-def.ts'
9
9
  import type { UnknownEvents } from './unknown-events.ts'
10
10
  import { normalizeUnknownEventHandling } from './unknown-events.ts'
@@ -381,6 +381,19 @@ describe('getColumnDefForSchema', () => {
381
381
  expect((table.rowSchema as any).fields.count.toString()).toBe('Int | null')
382
382
  })
383
383
 
384
+ it('should treat unions of string literals as text columns without JSON parsing', () => {
385
+ const schema = Schema.Struct({
386
+ id: Schema.String,
387
+ status: Schema.Literal('idle', 'running', 'stopped'),
388
+ })
389
+
390
+ const table = State.SQLite.table({ name: 'timers', schema })
391
+
392
+ expect(table.sqliteDef.columns.status.columnType).toBe('text')
393
+ expect(table.sqliteDef.columns.status.schema.toString()).toBe('"idle" | "running" | "stopped"')
394
+ expect((table.rowSchema as any).fields.status.toString()).toBe('"idle" | "running" | "stopped"')
395
+ })
396
+
384
397
  it('should handle Schema.NullOr with complex types', () => {
385
398
  const schema = Schema.Struct({
386
399
  data: Schema.NullOr(Schema.Struct({ value: Schema.Number })),
@@ -185,6 +185,10 @@ const getColumnForSchema = (schema: Schema.Schema.AnyNoContext, nullable = false
185
185
  if (typeof value === 'boolean') return SqliteDsl.boolean({ nullable })
186
186
  }
187
187
 
188
+ if (isLiteralUnionOf(coreAst, (value): value is string => typeof value === 'string')) {
189
+ return SqliteDsl.text({ schema: coreSchema, nullable })
190
+ }
191
+
188
192
  // Literals based on their encoded type
189
193
  if (SchemaAST.isLiteral(encodedAst)) {
190
194
  const value = encodedAst.literal
@@ -199,6 +203,10 @@ const getColumnForSchema = (schema: Schema.Schema.AnyNoContext, nullable = false
199
203
  }
200
204
  }
201
205
 
206
+ if (isLiteralUnionOf(encodedAst, (value): value is string => typeof value === 'string')) {
207
+ return SqliteDsl.text({ schema: coreSchema, nullable })
208
+ }
209
+
202
210
  // Everything else needs JSON encoding
203
211
  return SqliteDsl.json({ schema: coreSchema, nullable })
204
212
  }
@@ -221,3 +229,11 @@ const stripNullable = (ast: SchemaAST.AST): SchemaAST.AST => {
221
229
 
222
230
  return SchemaAST.Union.make(coreTypes, ast.annotations)
223
231
  }
232
+
233
+ const isLiteralUnionOf = <T extends SchemaAST.LiteralValue>(
234
+ ast: SchemaAST.AST,
235
+ predicate: (value: SchemaAST.LiteralValue) => value is T,
236
+ ): ast is SchemaAST.Union & { types: ReadonlyArray<SchemaAST.Literal & { literal: T }> } =>
237
+ SchemaAST.isUnion(ast) &&
238
+ ast.types.length > 0 &&
239
+ ast.types.every((type) => SchemaAST.isLiteral(type) && predicate(type.literal))
@@ -5,7 +5,7 @@ import type { Materializer } from '../../EventDef.ts'
5
5
  import type { InternalState } from '../../schema.ts'
6
6
  import { ClientDocumentTableDefSymbol, tableIsClientDocumentTable } from './client-document-def.ts'
7
7
  import { SqliteAst } from './db-schema/mod.ts'
8
- import { stateSystemTables } from './system-tables.ts'
8
+ import { stateSystemTables } from './system-tables/state-tables.ts'
9
9
  import type { TableDef, TableDefBase } from './table-def.ts'
10
10
 
11
11
  export * from '../../EventDef.ts'
@@ -0,0 +1,64 @@
1
+ import { Schema } from '@livestore/utils/effect'
2
+
3
+ import * as EventSequenceNumber from '../../../EventSequenceNumber.ts'
4
+ import { SqliteDsl } from '../db-schema/mod.ts'
5
+ import { table } from '../table-def.ts'
6
+
7
+ /**
8
+ * EVENTLOG DATABASE SYSTEM TABLES
9
+ *
10
+ * ⚠️ CRITICAL: NEVER modify eventlog schemas without bumping `liveStoreStorageFormatVersion`!
11
+ * Eventlog is the source of truth - schema changes cause permanent data loss.
12
+ *
13
+ * TODO: Implement proper eventlog versioning system to prevent accidental data loss
14
+ */
15
+
16
+ export const EVENTLOG_META_TABLE = 'eventlog'
17
+
18
+ /**
19
+ * Main client-side event log storing all events (global and local/rebased).
20
+ */
21
+ export const eventlogMetaTable = table({
22
+ name: EVENTLOG_META_TABLE,
23
+ columns: {
24
+ // TODO Adjust modeling so a global event never needs a client id component
25
+ seqNumGlobal: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.GlobalEventSequenceNumber }),
26
+ seqNumClient: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.ClientEventSequenceNumber }),
27
+ seqNumRebaseGeneration: SqliteDsl.integer({ primaryKey: true }),
28
+ parentSeqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
29
+ parentSeqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
30
+ parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
31
+ /** Event definition name */
32
+ name: SqliteDsl.text({}),
33
+ argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
34
+ clientId: SqliteDsl.text({}),
35
+ sessionId: SqliteDsl.text({}),
36
+ schemaHash: SqliteDsl.integer({}),
37
+ syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
38
+ },
39
+ indexes: [
40
+ { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },
41
+ { columns: ['seqNumGlobal', 'seqNumClient', 'seqNumRebaseGeneration'], name: 'idx_eventlog_seqNum' },
42
+ ],
43
+ })
44
+
45
+ export type EventlogMetaRow = typeof eventlogMetaTable.Type
46
+
47
+ export const SYNC_STATUS_TABLE = '__livestore_sync_status'
48
+
49
+ /**
50
+ * Tracks sync status including the remote head position and backend identity.
51
+ */
52
+ // TODO support sync backend identity (to detect if sync backend changes)
53
+ export const syncStatusTable = table({
54
+ name: SYNC_STATUS_TABLE,
55
+ columns: {
56
+ head: SqliteDsl.integer({ primaryKey: true }),
57
+ // Null means the sync backend is not yet connected and we haven't yet seen a backend ID
58
+ backendId: SqliteDsl.text({ nullable: true }),
59
+ },
60
+ })
61
+
62
+ export type SyncStatusRow = typeof syncStatusTable.Type
63
+
64
+ export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable] as const
@@ -0,0 +1,2 @@
1
+ export * from './eventlog-tables.ts'
2
+ export * from './state-tables.ts'
@@ -0,0 +1,69 @@
1
+ import * as EventSequenceNumber from '../../../EventSequenceNumber.ts'
2
+ import { SqliteDsl } from '../db-schema/mod.ts'
3
+ import { table } from '../table-def.ts'
4
+
5
+ /**
6
+ * STATE DATABASE SYSTEM TABLES
7
+ *
8
+ * ⚠️ SAFE TO CHANGE: State tables are automatically rebuilt from eventlog when schema changes.
9
+ * No need to bump `liveStoreStorageFormatVersion` (uses hash-based migration via SqliteAst.hash()).
10
+ */
11
+
12
+ export const SCHEMA_META_TABLE = '__livestore_schema'
13
+
14
+ /**
15
+ * Tracks schema hashes for user-defined tables to detect schema changes.
16
+ */
17
+ export const schemaMetaTable = table({
18
+ name: SCHEMA_META_TABLE,
19
+ columns: {
20
+ tableName: SqliteDsl.text({ primaryKey: true }),
21
+ schemaHash: SqliteDsl.integer({ nullable: false }),
22
+ /** ISO date format */
23
+ updatedAt: SqliteDsl.text({ nullable: false }),
24
+ },
25
+ })
26
+
27
+ export type SchemaMetaRow = typeof schemaMetaTable.Type
28
+
29
+ export const SCHEMA_EVENT_DEFS_META_TABLE = '__livestore_schema_event_defs'
30
+
31
+ /**
32
+ * Tracks schema hashes for event definitions to detect event schema changes.
33
+ */
34
+ export const schemaEventDefsMetaTable = table({
35
+ name: SCHEMA_EVENT_DEFS_META_TABLE,
36
+ columns: {
37
+ eventName: SqliteDsl.text({ primaryKey: true }),
38
+ schemaHash: SqliteDsl.integer({ nullable: false }),
39
+ /** ISO date format */
40
+ updatedAt: SqliteDsl.text({ nullable: false }),
41
+ },
42
+ })
43
+
44
+ export type SchemaEventDefsMetaRow = typeof schemaEventDefsMetaTable.Type
45
+
46
+ /**
47
+ * Table which stores SQLite changeset blobs which is used for rolling back
48
+ * read-model state during rebasing.
49
+ */
50
+ export const SESSION_CHANGESET_META_TABLE = '__livestore_session_changeset'
51
+
52
+ export const sessionChangesetMetaTable = table({
53
+ name: SESSION_CHANGESET_META_TABLE,
54
+ columns: {
55
+ // TODO bring back primary key
56
+ seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
57
+ seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
58
+ seqNumRebaseGeneration: SqliteDsl.integer({}),
59
+ changeset: SqliteDsl.blob({ nullable: true }),
60
+ debug: SqliteDsl.json({ nullable: true }),
61
+ },
62
+ indexes: [{ columns: ['seqNumGlobal', 'seqNumClient'], name: 'idx_session_changeset_id' }],
63
+ })
64
+
65
+ export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
66
+
67
+ export const stateSystemTables = [schemaMetaTable, schemaEventDefsMetaTable, sessionChangesetMetaTable] as const
68
+
69
+ export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)
@@ -1,3 +1,34 @@
1
+ /**
2
+ * AUTOMATIC HASH-BASED SCHEMA MIGRATIONS
3
+ *
4
+ * This module implements automatic schema versioning using hash-based change detection.
5
+ *
6
+ * ⚠️ CRITICAL DISTINCTION:
7
+ * - STATE TABLES (safe to modify): Changes trigger rematerialization from eventlog
8
+ * - EVENTLOG TABLES (NEVER modify): Changes cause data loss - need manual versioning!
9
+ *
10
+ * How it works:
11
+ * 1. Each table's schema is hashed using SqliteAst.hash()
12
+ * 2. Hashes are stored in SCHEMA_META_TABLE after successful migrations
13
+ * 3. On app start, current schema hashes are compared with stored hashes
14
+ * 4. Mismatches trigger migrations:
15
+ * - State tables: Recreated and repopulated from eventlog (safe, no data loss)
16
+ * - Eventlog tables: Uses 'create-if-not-exists' (UNSAFE - causes data loss!)
17
+ *
18
+ * State Table Changes (SAFE):
19
+ * - User-defined tables are rebuilt from eventlog
20
+ * - System tables (schemaMetaTable, etc.) are recreated
21
+ * - Data preserved through rematerializeFromEventlog()
22
+ *
23
+ * Eventlog Table Changes (UNSAFE):
24
+ * - eventlogMetaTable, syncStatusTable changes cause "soft reset"
25
+ * - Old table becomes inaccessible (but remains in DB)
26
+ * - No automatic migration - effectively data loss
27
+ * - TODO: Implement proper EVENTLOG_PERSISTENCE_FORMAT_VERSION system
28
+ *
29
+ * See system-tables/state-tables.ts and system-tables/eventlog-tables.ts for detailed documentation on each table type.
30
+ */
31
+
1
32
  import { memoizeByStringifyArgs } from '@livestore/utils'
2
33
  import { Effect } from '@livestore/utils/effect'
3
34
 
@@ -7,14 +38,14 @@ import type { UnexpectedError } from '../errors.ts'
7
38
  import type { LiveStoreSchema } from '../schema/mod.ts'
8
39
  import { makeColumnSpec } from '../schema/state/sqlite/column-spec.ts'
9
40
  import { SqliteAst } from '../schema/state/sqlite/db-schema/mod.ts'
10
- import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables.ts'
41
+ import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables/state-tables.ts'
11
42
  import {
12
43
  isStateSystemTable,
13
44
  SCHEMA_EVENT_DEFS_META_TABLE,
14
45
  SCHEMA_META_TABLE,
15
46
  schemaEventDefsMetaTable,
16
47
  stateSystemTables,
17
- } from '../schema/state/sqlite/system-tables.ts'
48
+ } from '../schema/state/sqlite/system-tables/state-tables.ts'
18
49
  import { sql } from '../util.ts'
19
50
  import type { SchemaManager } from './common.ts'
20
51
  import { dbExecute, dbSelect } from './common.ts'
package/src/version.ts CHANGED
@@ -2,13 +2,23 @@
2
2
  // import packageJson from '../package.json' with { type: 'json' }
3
3
  // export const liveStoreVersion = packageJson.version
4
4
 
5
- export const liveStoreVersion = '0.4.0-dev.12' as const
5
+ export const liveStoreVersion = '0.4.0-dev.13' as const
6
6
 
7
7
  /**
8
- * This version number is incremented whenever the internal storage format changes in a breaking way.
9
- * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
8
+ * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.
10
9
  *
11
- * While LiveStore is in beta, this might happen more frequently.
12
- * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
10
+ * Used to generate database file names (e.g., `eventlog@6.db`, `state@6.db`) across all client adapters.
11
+ *
12
+ * Bump required when:
13
+ * - Modifying eventlog system tables (eventlogMetaTable, syncStatusTable) in schema/state/sqlite/system-tables/eventlog-tables.ts
14
+ * - Changing columns, types, constraints, or indexes in eventlog tables
15
+ *
16
+ * Bump NOT required when:
17
+ * - Modifying STATE table schemas (auto-migrated via hash-based detection and rebuilt from eventlog)
18
+ * - Changing query patterns or client-side implementation details
19
+ *
20
+ * ⚠️ CRITICAL: Eventlog changes without bumping this version cause permanent data loss!
21
+ *
22
+ * Impact: Version changes trigger a "soft reset" - old data becomes inaccessible but remains on disk.
13
23
  */
14
24
  export const liveStoreStorageFormatVersion = 6
@@ -1,106 +0,0 @@
1
- import { Schema } from '@livestore/utils/effect'
2
-
3
- import * as EventSequenceNumber from '../../EventSequenceNumber.ts'
4
- import { SqliteDsl } from './db-schema/mod.ts'
5
- import { table } from './table-def.ts'
6
-
7
- /// State DB
8
-
9
- export const SCHEMA_META_TABLE = '__livestore_schema'
10
-
11
- export const schemaMetaTable = table({
12
- name: SCHEMA_META_TABLE,
13
- columns: {
14
- tableName: SqliteDsl.text({ primaryKey: true }),
15
- schemaHash: SqliteDsl.integer({ nullable: false }),
16
- /** ISO date format */
17
- updatedAt: SqliteDsl.text({ nullable: false }),
18
- },
19
- })
20
-
21
- export type SchemaMetaRow = typeof schemaMetaTable.Type
22
-
23
- export const SCHEMA_EVENT_DEFS_META_TABLE = '__livestore_schema_event_defs'
24
-
25
- export const schemaEventDefsMetaTable = table({
26
- name: SCHEMA_EVENT_DEFS_META_TABLE,
27
- columns: {
28
- eventName: SqliteDsl.text({ primaryKey: true }),
29
- schemaHash: SqliteDsl.integer({ nullable: false }),
30
- /** ISO date format */
31
- updatedAt: SqliteDsl.text({ nullable: false }),
32
- },
33
- })
34
-
35
- export type SchemaEventDefsMetaRow = typeof schemaEventDefsMetaTable.Type
36
-
37
- /**
38
- * Table which stores SQLite changeset blobs which is used for rolling back
39
- * read-model state during rebasing.
40
- */
41
- export const SESSION_CHANGESET_META_TABLE = '__livestore_session_changeset'
42
-
43
- export const sessionChangesetMetaTable = table({
44
- name: SESSION_CHANGESET_META_TABLE,
45
- columns: {
46
- // TODO bring back primary key
47
- seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
48
- seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
49
- seqNumRebaseGeneration: SqliteDsl.integer({}),
50
- changeset: SqliteDsl.blob({ nullable: true }),
51
- debug: SqliteDsl.json({ nullable: true }),
52
- },
53
- indexes: [{ columns: ['seqNumGlobal', 'seqNumClient'], name: 'idx_session_changeset_id' }],
54
- })
55
-
56
- export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
57
-
58
- export const stateSystemTables = [schemaMetaTable, schemaEventDefsMetaTable, sessionChangesetMetaTable] as const
59
-
60
- export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)
61
-
62
- /// Eventlog DB
63
-
64
- export const EVENTLOG_META_TABLE = 'eventlog'
65
-
66
- export const eventlogMetaTable = table({
67
- name: EVENTLOG_META_TABLE,
68
- columns: {
69
- // TODO Adjust modeling so a global event never needs a client id component
70
- seqNumGlobal: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.GlobalEventSequenceNumber }),
71
- seqNumClient: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.ClientEventSequenceNumber }),
72
- seqNumRebaseGeneration: SqliteDsl.integer({ primaryKey: true }),
73
- parentSeqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
74
- parentSeqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
75
- parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
76
- /** Event definition name */
77
- name: SqliteDsl.text({}),
78
- argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
79
- clientId: SqliteDsl.text({}),
80
- sessionId: SqliteDsl.text({}),
81
- schemaHash: SqliteDsl.integer({}),
82
- syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
83
- },
84
- indexes: [
85
- { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },
86
- { columns: ['seqNumGlobal', 'seqNumClient', 'seqNumRebaseGeneration'], name: 'idx_eventlog_seqNum' },
87
- ],
88
- })
89
-
90
- export type EventlogMetaRow = typeof eventlogMetaTable.Type
91
-
92
- export const SYNC_STATUS_TABLE = '__livestore_sync_status'
93
-
94
- // TODO support sync backend identity (to detect if sync backend changes)
95
- export const syncStatusTable = table({
96
- name: SYNC_STATUS_TABLE,
97
- columns: {
98
- head: SqliteDsl.integer({ primaryKey: true }),
99
- // Null means the sync backend is not yet connected and we haven't yet seen a backend ID
100
- backendId: SqliteDsl.text({ nullable: true }),
101
- },
102
- })
103
-
104
- export type SyncStatusRow = typeof syncStatusTable.Type
105
-
106
- export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable] as const