Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

node-persistence.ts

173 lines5.5 KB

1import {
2 DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS as CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS,
3 DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS as CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS,
4 SingleProcessCoordinator,
5 createSQLiteCorePersistenceAdapter,
6} from '@tanstack/db-sqlite-persistence-core'
7import { BetterSqlite3SQLiteDriver } from './node-driver'
8import type {
9 PersistedCollectionCoordinator,
10 PersistedCollectionMode,
11 PersistedCollectionPersistence,
12 SQLiteCoreAdapterOptions,
13 SQLiteDriver,
14} from '@tanstack/db-sqlite-persistence-core'
15import type { BetterSqlite3Database } from './node-driver'
16​
17export type { BetterSqlite3Database } from './node-driver'
18​
19type NodeSQLiteCoreSchemaMismatchPolicy =
20 `sync-present-reset` | `sync-absent-error` | `reset`
21​
22export type NodeSQLiteSchemaMismatchPolicy =
23 NodeSQLiteCoreSchemaMismatchPolicy | `throw`
24​
25type NodeSQLitePersistenceBaseOptions = Omit<
26 SQLiteCoreAdapterOptions,
27 `driver` | `schemaVersion` | `schemaMismatchPolicy`
28> & {
29 database: BetterSqlite3Database
30 pragmas?: ReadonlyArray<string>
31 coordinator?: PersistedCollectionCoordinator
32 schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy
34​
35export type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions
36​
37/**
38 * Default cap on retained `applied_tx` rows per collection. The log is a
39 * replayable cache, so a bounded row count keeps SQLite files from growing
40 * without limit. Pass `appliedTxPruneMaxRows: 0` to disable the row cap.
41 */
42export const DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS =
43 CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS
44​
45/**
46 * Default age backstop for retained `applied_tx` rows, in seconds (24h). Rows
47 * older than this are pruned on the next write. Pass
48 * `appliedTxPruneMaxAgeSeconds: 0` to disable the age backstop.
49 */
50export const DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS =
51 CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS
52​
53function normalizeSchemaMismatchPolicy(
54 policy: NodeSQLiteSchemaMismatchPolicy,
55): NodeSQLiteCoreSchemaMismatchPolicy {
56 if (policy === `throw`) {
57 return `sync-absent-error`
58 }
59​
60 return policy
62​
63function resolveSchemaMismatchPolicy(
64 explicitPolicy: NodeSQLiteSchemaMismatchPolicy | undefined,
65 mode: PersistedCollectionMode,
66): NodeSQLiteCoreSchemaMismatchPolicy {
67 if (explicitPolicy) {
68 return normalizeSchemaMismatchPolicy(explicitPolicy)
69 }
70​
71 return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`
73​
74function createAdapterCacheKey(
75 schemaMismatchPolicy: NodeSQLiteCoreSchemaMismatchPolicy,
76 schemaVersion: number | undefined,
77): string {
78 const schemaVersionKey =
79 schemaVersion === undefined ? `schema:default` : `schema:${schemaVersion}`
80 return `${schemaMismatchPolicy}|${schemaVersionKey}`
82​
83function createInternalSQLiteDriver(
84 options: NodeSQLitePersistenceOptions,
85): SQLiteDriver {
86 return new BetterSqlite3SQLiteDriver({
87 database: options.database,
88 ...(options.pragmas ? { pragmas: options.pragmas } : {}),
89 })
91​
92function resolveAdapterBaseOptions(
93 options: NodeSQLitePersistenceOptions,
94): Omit<
95 SQLiteCoreAdapterOptions,
96 `driver` | `schemaVersion` | `schemaMismatchPolicy`
97> {
98 return {
99 appliedTxPruneMaxRows:
100 options.appliedTxPruneMaxRows ?? CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS,
101 appliedTxPruneMaxAgeSeconds:
102 options.appliedTxPruneMaxAgeSeconds ??
103 CORE_DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS,
104 pullSinceReloadThreshold: options.pullSinceReloadThreshold,
105 }
107​
108/**
109 * Creates a shared SQLite persistence instance that can be reused by many
110 * collections on the same database. Collection-specific schema versions are
111 * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.
112 */
113export function createNodeSQLitePersistence(
114 options: NodeSQLitePersistenceOptions,
115): PersistedCollectionPersistence {
116 const { coordinator, schemaMismatchPolicy } = options
117 const driver = createInternalSQLiteDriver(options)
118 const adapterBaseOptions = resolveAdapterBaseOptions(options)
119 const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator()
120 const adapterCache = new Map<
121 string,
122 ReturnType<typeof createSQLiteCorePersistenceAdapter>
123 >()
124​
125 const getAdapterForCollection = (
126 mode: PersistedCollectionMode,
127 schemaVersion: number | undefined,
128 ) => {
129 const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(
130 schemaMismatchPolicy,
131 mode,
132 )
133 const cacheKey = createAdapterCacheKey(
134 resolvedSchemaMismatchPolicy,
135 schemaVersion,
136 )
137 const cachedAdapter = adapterCache.get(cacheKey)
138 if (cachedAdapter) {
139 return cachedAdapter
140 }
141​
142 const adapter = createSQLiteCorePersistenceAdapter({
143 ...adapterBaseOptions,
144 driver,
145 schemaMismatchPolicy: resolvedSchemaMismatchPolicy,
146 ...(schemaVersion === undefined ? {} : { schemaVersion }),
147 })
148 adapterCache.set(cacheKey, adapter)
149 return adapter
150 }
151​
152 const createCollectionPersistence = (
153 mode: PersistedCollectionMode,
154 schemaVersion: number | undefined,
155 ): PersistedCollectionPersistence => ({
156 adapter: getAdapterForCollection(mode, schemaVersion),
157 coordinator: resolvedCoordinator,
158 })
159​
160 const defaultPersistence = createCollectionPersistence(
161 `sync-absent`,
162 undefined,
163 )
164​
165 return {
166 ...defaultPersistence,
167 resolvePersistenceForCollection: ({ mode, schemaVersion }) =>
168 createCollectionPersistence(mode, schemaVersion),
169 // Backward compatible fallback for older callers.
170 resolvePersistenceForMode: (mode) =>
171 createCollectionPersistence(mode, undefined),
172 }