@starkeep/storage-sqlite 0.3.1 → 0.5.0

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.
package/README.md CHANGED
@@ -45,10 +45,10 @@ await databaseAdapter.close();
45
45
 
46
46
  ## API
47
47
 
48
- | Export | Description |
49
- |---|---|
50
- | `SqliteDatabaseAdapter` | Class implementing `DatabaseAdapter` for SQLite |
51
- | `SqliteDatabaseAdapterOptions` | Options type: `{ path: string \| ":memory:" }` |
48
+ | Export | Description |
49
+ | ------------------------------ | ----------------------------------------------- |
50
+ | `SqliteDatabaseAdapter` | Class implementing `DatabaseAdapter` for SQLite |
51
+ | `SqliteDatabaseAdapterOptions` | Options type: `{ path: string \| ":memory:" }` |
52
52
 
53
53
  The adapter automatically creates the `records` table, indexes, and a `migrations` table on `init()`. WAL journal mode and foreign keys are enabled by default.
54
54
 
@@ -0,0 +1,126 @@
1
+ import { DatabaseAdapter, RawDatabase, SincePage, DigestBucket, Query, QueryResult, RecordTypeCount, SharedQueryTarget, ParsedQuery, WhereClause, SoftDeletedScope, ParsedQueryResult, BatchOperation, Transaction, LabelUpsert, LabelRetraction, LabelValueReplacement, FindByLabelQuery, FindByLabelResult, StoredAvailability } from '@starkeep/storage-adapter';
2
+ import { DataRecord, StarkeepId, HLCTimestamp, RecordLabel, MetadataRow } from '@starkeep/protocol-primitives';
3
+
4
+ interface SqliteDatabaseAdapterOptions {
5
+ path: string | ":memory:";
6
+ /**
7
+ * How to open the connection, and how to close it.
8
+ *
9
+ * Injected so a second SQLite driver can back this adapter rather than
10
+ * duplicating it. Everything below this line already speaks only
11
+ * {@link RawDatabase} — `exec` and `prepare` — which is what item 10
12
+ * established; opening the connection was the single remaining line that
13
+ * named `node:sqlite`, and it is the one thing that genuinely cannot be
14
+ * driver-agnostic.
15
+ *
16
+ * **Required, and deliberately without a default.** It used to default to
17
+ * `node:sqlite`, which meant this module imported it statically — and a static
18
+ * `node:` import at module scope makes the whole package unbundleable on React
19
+ * Native, whatever driver the caller then passes. The Node driver now lives at
20
+ * `@starkeep/storage-sqlite/node`, so a Node caller writes one extra import
21
+ * and a handset can bundle this file at all.
22
+ *
23
+ * A default that only works on some platforms is worse than no default: it
24
+ * fails at bundle time, far from the line that chose it.
25
+ *
26
+ * React Native passes an op-sqlite driver; see `src/db/op-sqlite-driver.ts` in
27
+ * the `starkeep-apps` photos-mobile app for why that one emulates `prepare()`
28
+ * rather than using op-sqlite's prepared statements.
29
+ */
30
+ driver: SqliteDriver;
31
+ }
32
+ interface SqliteDriver {
33
+ open(path: string): RawDatabase;
34
+ /**
35
+ * Separate from the connection because `RawDatabase` deliberately does not
36
+ * carry `close()`. Consumers of a connection have no business closing it —
37
+ * only whoever opened it does, which is this adapter.
38
+ */
39
+ close(db: RawDatabase): void;
40
+ }
41
+ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
42
+ private database;
43
+ private readonly options;
44
+ private readonly driver;
45
+ constructor(options: SqliteDatabaseAdapterOptions);
46
+ init(): Promise<void>;
47
+ close(): Promise<void>;
48
+ healthCheck(): Promise<boolean>;
49
+ private getDatabase;
50
+ /**
51
+ * The raw SQLite connection, so sibling subsystems (the sync engine's change
52
+ * log and state store, the resident set) can create side tables in the same
53
+ * database file. Only valid after `init()`.
54
+ *
55
+ * Typed as {@link RawDatabase} rather than `DatabaseSync`: returning the
56
+ * concrete Node type is what made a second driver impossible, since every
57
+ * consumer was then nailed to `node:sqlite`, which React Native does not
58
+ * have. `DatabaseSync` satisfies the narrower interface structurally, so
59
+ * nothing about this connection changes — only what callers may reach for.
60
+ */
61
+ getRawDatabase(): RawDatabase;
62
+ private runStmt;
63
+ private getRow;
64
+ private allRows;
65
+ put(record: DataRecord): Promise<void>;
66
+ get(id: StarkeepId): Promise<DataRecord | null>;
67
+ delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
68
+ getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
69
+ querySince(peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<SincePage<DataRecord>>;
70
+ queryLabelsSince(peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<SincePage<RecordLabel>>;
71
+ bucketDigest(prefixLength?: number): Promise<DigestBucket[]>;
72
+ query(query: Query): Promise<QueryResult>;
73
+ countRecords(query: Query): Promise<number>;
74
+ countRecordsByType(query: Query): Promise<RecordTypeCount[]>;
75
+ /**
76
+ * See `DatabaseAdapter.queryShared`. Compiled by the same builder the
77
+ * app-syncable plane uses, against the table the target names on this engine.
78
+ */
79
+ queryShared(target: SharedQueryTarget, query: ParsedQuery, options?: {
80
+ readonly serverWhere?: readonly WhereClause[];
81
+ readonly softDeleted?: SoftDeletedScope;
82
+ }): Promise<ParsedQueryResult>;
83
+ /** Bind and run a compiled SELECT, adapting values SQLite cannot bind. */
84
+ private selectCompiled;
85
+ batch(operations: BatchOperation[]): Promise<void>;
86
+ transaction<T>(callback: (transaction: Transaction) => Promise<T>): Promise<T>;
87
+ putMetadata(recordType: string, row: MetadataRow): Promise<void>;
88
+ getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
89
+ getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
90
+ deleteMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
91
+ tombstoneMetadata(typeId: string, recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
92
+ restoreMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
93
+ private setMetadataTombstone;
94
+ upsertLabels(labels: LabelUpsert[]): Promise<void>;
95
+ retractLabels(retractions: LabelRetraction[]): Promise<void>;
96
+ replaceLabelValues(replacements: LabelValueReplacement[]): Promise<void>;
97
+ getLabelsByRecordIds(recordIds: StarkeepId[]): Promise<Map<StarkeepId, RecordLabel[]>>;
98
+ /**
99
+ * The reverse label read, run through the query grammar — see
100
+ * `label-find.ts`. The grant rides in as `serverWhere` rather than as one of
101
+ * the caller's own predicates, which is the separation every other shared
102
+ * query draws.
103
+ */
104
+ findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
105
+ putLabel(label: RecordLabel): Promise<void>;
106
+ getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
107
+ queryLabels(query: {
108
+ limit?: number;
109
+ cursor?: string;
110
+ }): Promise<{
111
+ labels: RecordLabel[];
112
+ nextCursor: string | null;
113
+ hasMore: boolean;
114
+ }>;
115
+ getLabelNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
116
+ getAvailability(objectStorageKeys: string[]): Promise<Map<string, StoredAvailability>>;
117
+ putAvailability(row: StoredAvailability): Promise<void>;
118
+ countRestoringObjects(): Promise<{
119
+ objectCount: number;
120
+ bytes: number;
121
+ }>;
122
+ tombstoneLabelsForRecord(recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
123
+ restoreLabelsForRecord(recordId: StarkeepId, deletedAt: HLCTimestamp, hlc: HLCTimestamp): Promise<void>;
124
+ }
125
+
126
+ export { SqliteDatabaseAdapter as S, type SqliteDatabaseAdapterOptions as a, type SqliteDriver as b };
@@ -0,0 +1,126 @@
1
+ import { DatabaseAdapter, RawDatabase, SincePage, DigestBucket, Query, QueryResult, RecordTypeCount, SharedQueryTarget, ParsedQuery, WhereClause, SoftDeletedScope, ParsedQueryResult, BatchOperation, Transaction, LabelUpsert, LabelRetraction, LabelValueReplacement, FindByLabelQuery, FindByLabelResult, StoredAvailability } from '@starkeep/storage-adapter';
2
+ import { DataRecord, StarkeepId, HLCTimestamp, RecordLabel, MetadataRow } from '@starkeep/protocol-primitives';
3
+
4
+ interface SqliteDatabaseAdapterOptions {
5
+ path: string | ":memory:";
6
+ /**
7
+ * How to open the connection, and how to close it.
8
+ *
9
+ * Injected so a second SQLite driver can back this adapter rather than
10
+ * duplicating it. Everything below this line already speaks only
11
+ * {@link RawDatabase} — `exec` and `prepare` — which is what item 10
12
+ * established; opening the connection was the single remaining line that
13
+ * named `node:sqlite`, and it is the one thing that genuinely cannot be
14
+ * driver-agnostic.
15
+ *
16
+ * **Required, and deliberately without a default.** It used to default to
17
+ * `node:sqlite`, which meant this module imported it statically — and a static
18
+ * `node:` import at module scope makes the whole package unbundleable on React
19
+ * Native, whatever driver the caller then passes. The Node driver now lives at
20
+ * `@starkeep/storage-sqlite/node`, so a Node caller writes one extra import
21
+ * and a handset can bundle this file at all.
22
+ *
23
+ * A default that only works on some platforms is worse than no default: it
24
+ * fails at bundle time, far from the line that chose it.
25
+ *
26
+ * React Native passes an op-sqlite driver; see `src/db/op-sqlite-driver.ts` in
27
+ * the `starkeep-apps` photos-mobile app for why that one emulates `prepare()`
28
+ * rather than using op-sqlite's prepared statements.
29
+ */
30
+ driver: SqliteDriver;
31
+ }
32
+ interface SqliteDriver {
33
+ open(path: string): RawDatabase;
34
+ /**
35
+ * Separate from the connection because `RawDatabase` deliberately does not
36
+ * carry `close()`. Consumers of a connection have no business closing it —
37
+ * only whoever opened it does, which is this adapter.
38
+ */
39
+ close(db: RawDatabase): void;
40
+ }
41
+ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
42
+ private database;
43
+ private readonly options;
44
+ private readonly driver;
45
+ constructor(options: SqliteDatabaseAdapterOptions);
46
+ init(): Promise<void>;
47
+ close(): Promise<void>;
48
+ healthCheck(): Promise<boolean>;
49
+ private getDatabase;
50
+ /**
51
+ * The raw SQLite connection, so sibling subsystems (the sync engine's change
52
+ * log and state store, the resident set) can create side tables in the same
53
+ * database file. Only valid after `init()`.
54
+ *
55
+ * Typed as {@link RawDatabase} rather than `DatabaseSync`: returning the
56
+ * concrete Node type is what made a second driver impossible, since every
57
+ * consumer was then nailed to `node:sqlite`, which React Native does not
58
+ * have. `DatabaseSync` satisfies the narrower interface structurally, so
59
+ * nothing about this connection changes — only what callers may reach for.
60
+ */
61
+ getRawDatabase(): RawDatabase;
62
+ private runStmt;
63
+ private getRow;
64
+ private allRows;
65
+ put(record: DataRecord): Promise<void>;
66
+ get(id: StarkeepId): Promise<DataRecord | null>;
67
+ delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
68
+ getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
69
+ querySince(peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<SincePage<DataRecord>>;
70
+ queryLabelsSince(peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<SincePage<RecordLabel>>;
71
+ bucketDigest(prefixLength?: number): Promise<DigestBucket[]>;
72
+ query(query: Query): Promise<QueryResult>;
73
+ countRecords(query: Query): Promise<number>;
74
+ countRecordsByType(query: Query): Promise<RecordTypeCount[]>;
75
+ /**
76
+ * See `DatabaseAdapter.queryShared`. Compiled by the same builder the
77
+ * app-syncable plane uses, against the table the target names on this engine.
78
+ */
79
+ queryShared(target: SharedQueryTarget, query: ParsedQuery, options?: {
80
+ readonly serverWhere?: readonly WhereClause[];
81
+ readonly softDeleted?: SoftDeletedScope;
82
+ }): Promise<ParsedQueryResult>;
83
+ /** Bind and run a compiled SELECT, adapting values SQLite cannot bind. */
84
+ private selectCompiled;
85
+ batch(operations: BatchOperation[]): Promise<void>;
86
+ transaction<T>(callback: (transaction: Transaction) => Promise<T>): Promise<T>;
87
+ putMetadata(recordType: string, row: MetadataRow): Promise<void>;
88
+ getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
89
+ getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
90
+ deleteMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
91
+ tombstoneMetadata(typeId: string, recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
92
+ restoreMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
93
+ private setMetadataTombstone;
94
+ upsertLabels(labels: LabelUpsert[]): Promise<void>;
95
+ retractLabels(retractions: LabelRetraction[]): Promise<void>;
96
+ replaceLabelValues(replacements: LabelValueReplacement[]): Promise<void>;
97
+ getLabelsByRecordIds(recordIds: StarkeepId[]): Promise<Map<StarkeepId, RecordLabel[]>>;
98
+ /**
99
+ * The reverse label read, run through the query grammar — see
100
+ * `label-find.ts`. The grant rides in as `serverWhere` rather than as one of
101
+ * the caller's own predicates, which is the separation every other shared
102
+ * query draws.
103
+ */
104
+ findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
105
+ putLabel(label: RecordLabel): Promise<void>;
106
+ getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
107
+ queryLabels(query: {
108
+ limit?: number;
109
+ cursor?: string;
110
+ }): Promise<{
111
+ labels: RecordLabel[];
112
+ nextCursor: string | null;
113
+ hasMore: boolean;
114
+ }>;
115
+ getLabelNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
116
+ getAvailability(objectStorageKeys: string[]): Promise<Map<string, StoredAvailability>>;
117
+ putAvailability(row: StoredAvailability): Promise<void>;
118
+ countRestoringObjects(): Promise<{
119
+ objectCount: number;
120
+ bytes: number;
121
+ }>;
122
+ tombstoneLabelsForRecord(recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
123
+ restoreLabelsForRecord(recordId: StarkeepId, deletedAt: HLCTimestamp, hlc: HLCTimestamp): Promise<void>;
124
+ }
125
+
126
+ export { SqliteDatabaseAdapter as S, type SqliteDatabaseAdapterOptions as a, type SqliteDriver as b };