@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 +4 -4
- package/dist/adapter-DoVOV6K-.d.cts +126 -0
- package/dist/adapter-DoVOV6K-.d.ts +126 -0
- package/dist/index.cjs +617 -214
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +172 -71
- package/dist/index.d.ts +172 -71
- package/dist/index.js +645 -193
- package/dist/index.js.map +1 -1
- package/dist/node-entry.cjs +45 -0
- package/dist/node-entry.cjs.map +1 -0
- package/dist/node-entry.d.cts +32 -0
- package/dist/node-entry.d.ts +32 -0
- package/dist/node-entry.js +18 -0
- package/dist/node-entry.js.map +1 -0
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -45,10 +45,10 @@ await databaseAdapter.close();
|
|
|
45
45
|
|
|
46
46
|
## API
|
|
47
47
|
|
|
48
|
-
| Export
|
|
49
|
-
|
|
50
|
-
| `SqliteDatabaseAdapter`
|
|
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 };
|