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

node-persistence.ts

175 lines5.6 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 cacheGenerationClaimTtlMs: options.cacheGenerationClaimTtlMs,
106 now: options.now,
107 }
109​
110/**
111 * Creates a shared SQLite persistence instance that can be reused by many
112 * collections on the same database. Collection-specific schema versions are
113 * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.
114 */
115export function createNodeSQLitePersistence(
116 options: NodeSQLitePersistenceOptions,
117): PersistedCollectionPersistence {
118 const { coordinator, schemaMismatchPolicy } = options
119 const driver = createInternalSQLiteDriver(options)
120 const adapterBaseOptions = resolveAdapterBaseOptions(options)
121 const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator()
122 const adapterCache = new Map<
123 string,
124 ReturnType<typeof createSQLiteCorePersistenceAdapter>
125 >()
126​
127 const getAdapterForCollection = (
128 mode: PersistedCollectionMode,
129 schemaVersion: number | undefined,
130 ) => {
131 const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(
132 schemaMismatchPolicy,
133 mode,
134 )
135 const cacheKey = createAdapterCacheKey(
136 resolvedSchemaMismatchPolicy,
137 schemaVersion,
138 )
139 const cachedAdapter = adapterCache.get(cacheKey)
140 if (cachedAdapter) {
141 return cachedAdapter
142 }
143​
144 const adapter = createSQLiteCorePersistenceAdapter({
145 ...adapterBaseOptions,
146 driver,
147 schemaMismatchPolicy: resolvedSchemaMismatchPolicy,
148 ...(schemaVersion === undefined ? {} : { schemaVersion }),
149 })
150 adapterCache.set(cacheKey, adapter)
151 return adapter
152 }
153​
154 const createCollectionPersistence = (
155 mode: PersistedCollectionMode,
156 schemaVersion: number | undefined,
157 ): PersistedCollectionPersistence => ({
158 adapter: getAdapterForCollection(mode, schemaVersion),
159 coordinator: resolvedCoordinator,
160 })
161​
162 const defaultPersistence = createCollectionPersistence(
163 `sync-absent`,
164 undefined,
165 )
166​
167 return {
168 ...defaultPersistence,
169 resolvePersistenceForCollection: ({ mode, schemaVersion }) =>
170 createCollectionPersistence(mode, schemaVersion),
171 // Backward compatible fallback for older callers.
172 resolvePersistenceForMode: (mode) =>
173 createCollectionPersistence(mode, undefined),
174 }