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

node-persistence.ts

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