@ocap/statedb-sqlite 1.30.24 → 1.30.26

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/lib/kysely.d.cts CHANGED
@@ -1,14 +1,64 @@
1
1
  import { Database } from "./interfaces.cjs";
2
- import { Kysely } from "kysely";
2
+ import { ITrustedStorage } from "@ocap/types";
3
+ import { DatabaseConnection, Dialect, Driver, Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler } from "kysely";
3
4
 
4
5
  //#region src/kysely.d.ts
5
6
 
7
+ /**
8
+ * Minimal Cloudflare Durable Object `SqlStorageCursor` contract (`ctx.storage.sql.exec(...)`).
9
+ */
10
+ interface IDurableObjectSqlStorageCursor<T = Record<string, unknown>> {
11
+ toArray(): T[];
12
+ one?(): T;
13
+ raw?<U = unknown[]>(): IterableIterator<U> | U[];
14
+ columnNames?: string[];
15
+ rowsRead?: number;
16
+ rowsWritten?: number;
17
+ [Symbol.iterator]?(): IterableIterator<T>;
18
+ }
19
+ /**
20
+ * Minimal Cloudflare Durable Object `SqlStorage` contract (`ctx.storage.sql`).
21
+ */
22
+ interface IDurableObjectSqlStorage {
23
+ exec<T = Record<string, unknown>>(query: string, ...bindings: unknown[]): IDurableObjectSqlStorageCursor<T>;
24
+ /**
25
+ * Optional Durable Object runtime transaction closure (`ctx.storage.transaction.bind(ctx.storage)`).
26
+ * When omitted, `DurableObjectSqliteDialect` still provides full atomic rollback via
27
+ * per-statement SQLite trigger undo logs and crash-recovery metadata without emitting
28
+ * forbidden BEGIN/SAVEPOINT SQL.
29
+ */
30
+ transaction?<T>(closure: () => Promise<T>): Promise<T>;
31
+ databaseSize?: number;
32
+ }
33
+ interface DurableObjectSqliteDialectConfig {
34
+ storage: IDurableObjectSqlStorage;
35
+ onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
36
+ }
37
+ declare function getDoStorageWriteEpoch(storage: IDurableObjectSqlStorage): number;
38
+ /**
39
+ * Kysely Dialect for Cloudflare Durable Object SQLite (`ctx.storage.sql`).
40
+ */
41
+ declare class DurableObjectSqliteDialect implements Dialect {
42
+ private readonly config;
43
+ private readonly createdOrder;
44
+ constructor(config: DurableObjectSqliteDialectConfig);
45
+ createDriver(): Driver;
46
+ createQueryCompiler(): SqliteQueryCompiler;
47
+ createAdapter(): SqliteAdapter;
48
+ createIntrospector(db: Kysely<any>): SqliteIntrospector;
49
+ }
6
50
  /**
7
51
  * SQLite configuration options
8
52
  */
9
53
  interface SqliteConfig {
10
54
  /** Database file path. Use ':memory:' for in-memory database */
11
- filename: string;
55
+ filename?: string;
56
+ /** Cloudflare Durable Object `ctx.storage.sql` instance */
57
+ doStorage?: IDurableObjectSqlStorage;
58
+ /** Custom Kysely Dialect override */
59
+ dialect?: Dialect;
60
+ /** Optional trusted storage instance for state commit hash verification */
61
+ trustedStorage?: ITrustedStorage;
12
62
  /** Open database in readonly mode */
13
63
  readonly?: boolean;
14
64
  /** Throw error if file doesn't exist (default: false, creates new file) */
@@ -27,10 +77,22 @@ interface SqliteConfig {
27
77
  * provided. If neither is set, SQLite's default (1000) is left untouched.
28
78
  */
29
79
  walAutoCheckpoint?: number;
80
+ /**
81
+ * Optional interval (in ms) for a background passive WAL checkpoint worker
82
+ * (`PRAGMA wal_checkpoint(PASSIVE)`). When > 0 and WAL mode is enabled, a
83
+ * non-blocking (`unref()`ed) periodic timer checkpoints frames back to the
84
+ * main DB file out-of-band without blocking readers or writers.
85
+ *
86
+ * Falls back to `SQLITE_WAL_CHECKPOINT_INTERVAL_MS` env when not provided.
87
+ * Disabled by default (0 / undefined).
88
+ */
89
+ walCheckpointIntervalMs?: number;
30
90
  }
91
+ declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number | undefined;
31
92
  /**
32
93
  * Create a Kysely instance with SQLite dialect
33
- * Automatically uses kysely-bun-sqlite in Bun or better-sqlite3 in Node.js
94
+ * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
95
+ * custom `config.dialect` when provided, kysely-bun-sqlite in Bun, or better-sqlite3 in Node.js
34
96
  *
35
97
  * @param config - SQLite configuration
36
98
  * @returns Kysely instance configured for the database
@@ -52,4 +114,4 @@ declare function createKysely(config: SqliteConfig): Kysely<Database>;
52
114
  */
53
115
  declare function getRawDatabase(db: Kysely<Database>): any;
54
116
  //#endregion
55
- export { SqliteConfig, createKysely, getRawDatabase };
117
+ export { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, resolveWalCheckpointIntervalMs };
package/lib/package.cjs CHANGED
@@ -11,7 +11,7 @@ var package_default = {
11
11
  },
12
12
  publishConfig: { "access": "public" },
13
13
  contributors: ["wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"],
14
- devDependencies: {},
14
+ devDependencies: { "@ocap/statedb-test": "workspace:*" },
15
15
  homepage: "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
16
16
  keywords: [
17
17
  "ocap",
@@ -4,6 +4,8 @@ const require_table_base = require('./base.cjs');
4
4
  let _ocap_state_lib_states_account = require("@ocap/state/lib/states/account");
5
5
 
6
6
  //#region src/table/balance.ts
7
+ const BATCH_COLLECTOR = Symbol.for("@ocap/statedb-sqlite.balanceBatchCollector");
8
+ const UPSERT_BATCH_SIZE = 200;
7
9
  /**
8
10
  * Balance Table
9
11
  * Manages token balances with composite primary key (address, tokenAddress)
@@ -17,6 +19,42 @@ var BalanceTable = class extends require_table_base.default {
17
19
  schema: { jsonFields: ["context"] }
18
20
  });
19
21
  }
22
+ generatePrimaryKey(doc) {
23
+ if (typeof doc === "object" && doc !== null && typeof doc.address === "string") return super.generatePrimaryKey({
24
+ ...doc,
25
+ address: (0, _ocap_state_lib_states_account.ensureChecksumAddress)(doc.address)
26
+ });
27
+ return super.generatePrimaryKey(doc);
28
+ }
29
+ formatKeyToQuery(key) {
30
+ const query = super.formatKeyToQuery(key);
31
+ if (typeof query.address === "string") query.address = (0, _ocap_state_lib_states_account.ensureChecksumAddress)(query.address);
32
+ return query;
33
+ }
34
+ async _create(key, attrs = {}, context) {
35
+ const collector = attrs?.[BATCH_COLLECTOR];
36
+ if (collector) {
37
+ const insertAttrs = {
38
+ ...attrs,
39
+ ...typeof key === "object" ? key : {}
40
+ };
41
+ collector.push(this.serializeForDb(insertAttrs));
42
+ return insertAttrs;
43
+ }
44
+ return super._create(key, attrs, context);
45
+ }
46
+ async _update(key, updates, context) {
47
+ const collector = updates?.[BATCH_COLLECTOR];
48
+ if (collector) {
49
+ const merged = {
50
+ ...updates,
51
+ ...typeof key === "object" ? key : {}
52
+ };
53
+ collector.push(this.serializeForDb(merged));
54
+ return merged;
55
+ }
56
+ return super._update(key, updates, context);
57
+ }
20
58
  /**
21
59
  * Get all token balances for an address
22
60
  *
@@ -35,7 +73,7 @@ var BalanceTable = class extends require_table_base.default {
35
73
  }
36
74
  /**
37
75
  * Update token balances for an address
38
- * Creates new records for new tokens, updates existing ones
76
+ * Creates new records for new tokens, updates existing ones via batched SQLite UPSERT
39
77
  *
40
78
  * @param params - Update parameters
41
79
  * @param ctx - Operation context
@@ -43,25 +81,41 @@ var BalanceTable = class extends require_table_base.default {
43
81
  */
44
82
  async updateBalance({ address, tokens, context = {} }, ctx) {
45
83
  if (!Object.keys(tokens).length) return {};
46
- const tokenBalances = await this.getBalance(address, ctx);
84
+ const normalizedAddress = (0, _ocap_state_lib_states_account.ensureChecksumAddress)(address);
85
+ const tokenBalances = await this.getBalance(normalizedAddress, ctx);
47
86
  const updatedTokens = Object.keys(tokens).filter((token) => tokenBalances[token] && tokenBalances[token] !== "0" || tokens[token] && tokens[token] !== "0").filter((token) => tokenBalances[token] !== tokens[token]);
48
- await Promise.all(updatedTokens.map(async (tokenAddress) => {
87
+ if (updatedTokens.length === 0) return tokens;
88
+ const batchRows = [];
89
+ for (const tokenAddress of updatedTokens) {
49
90
  const key = {
50
- address,
91
+ address: normalizedAddress,
51
92
  tokenAddress
52
93
  };
53
- if (tokenBalances[tokenAddress]) await this.update(key, {
54
- ...key,
55
- balance: tokens[tokenAddress],
56
- context
57
- }, ctx);
58
- else await this.create(key, {
94
+ const payload = {
59
95
  ...key,
60
96
  balance: tokens[tokenAddress],
61
97
  context
62
- }, ctx);
98
+ };
99
+ Object.defineProperty(payload, BATCH_COLLECTOR, {
100
+ value: batchRows,
101
+ enumerable: false,
102
+ configurable: true
103
+ });
104
+ if (tokenBalances[tokenAddress]) await this.update(key, payload, ctx);
105
+ else await this.create(key, payload, ctx);
63
106
  tokenBalances[tokenAddress] = tokens[tokenAddress];
64
- }));
107
+ }
108
+ if (batchRows.length > 0) {
109
+ const sqlContext = ctx;
110
+ const executor = this.getExecutor(sqlContext);
111
+ for (let i = 0; i < batchRows.length; i += UPSERT_BATCH_SIZE) {
112
+ const batch = batchRows.slice(i, i + UPSERT_BATCH_SIZE);
113
+ await executor.insertInto("balance").values(batch).onConflict((oc) => oc.columns(["address", "tokenAddress"]).doUpdateSet((eb) => ({
114
+ balance: eb.ref("excluded.balance"),
115
+ context: eb.ref("excluded.context")
116
+ }))).execute();
117
+ }
118
+ }
65
119
  return tokens;
66
120
  }
67
121
  };
@@ -9,6 +9,10 @@ import { IBalanceState, IOperationContext } from "@ocap/types";
9
9
  */
10
10
  declare class BalanceTable extends SqliteTable<IBalanceState> {
11
11
  constructor(config: Omit<SqliteTableConfig, 'name' | 'uniqIndex' | 'schema'>);
12
+ generatePrimaryKey(doc: string | Record<string, unknown>): string;
13
+ protected formatKeyToQuery(key: unknown): Record<string, unknown>;
14
+ _create(key: string | Record<string, unknown>, attrs?: Partial<IBalanceState>, context?: IOperationContext): Promise<IBalanceState>;
15
+ _update(key: string | Record<string, unknown>, updates: Partial<IBalanceState>, context?: IOperationContext): Promise<IBalanceState>;
12
16
  /**
13
17
  * Get all token balances for an address
14
18
  *
@@ -19,7 +23,7 @@ declare class BalanceTable extends SqliteTable<IBalanceState> {
19
23
  getBalance(address: string, _context?: IOperationContext): Promise<Record<string, string>>;
20
24
  /**
21
25
  * Update token balances for an address
22
- * Creates new records for new tokens, updates existing ones
26
+ * Creates new records for new tokens, updates existing ones via batched SQLite UPSERT
23
27
  *
24
28
  * @param params - Update parameters
25
29
  * @param ctx - Operation context
@@ -1,8 +1,8 @@
1
1
  Object.defineProperty(exports, '__esModule', { value: true });
2
2
  const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
3
- let _ocap_statedb = require("@ocap/statedb");
4
3
  let node_crypto = require("node:crypto");
5
4
  node_crypto = require_rolldown_runtime.__toESM(node_crypto);
5
+ let _ocap_statedb = require("@ocap/statedb");
6
6
  let lodash_omit = require("lodash/omit");
7
7
  lodash_omit = require_rolldown_runtime.__toESM(lodash_omit);
8
8
 
@@ -35,7 +35,7 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
35
35
  generatePrimaryKey(doc) {
36
36
  if (typeof doc === "string") return doc;
37
37
  if (Array.isArray(this.uniqIndex)) {
38
- const key = this.uniqIndex.map((id) => doc[id]).map((item) => typeof item === "object" ? JSON.stringify(item) : item).join("-");
38
+ const key = this.uniqIndex.map((id) => doc[id]).map((item) => typeof item === "object" ? JSON.stringify(item) : String(item ?? "")).map((item) => item.replace(/\\/g, "\\\\").replace(/-/g, "\\-")).join("-");
39
39
  return node_crypto.default.createHash("md5").update(key).digest("hex");
40
40
  }
41
41
  return doc[this.uniqIndex];
@@ -140,10 +140,8 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
140
140
  const sqlContext = context;
141
141
  const executor = this.getExecutor(sqlContext);
142
142
  let query;
143
- if (Array.isArray(this.uniqIndex)) if (typeof key === "object") {
144
- const keyObj = key;
145
- query = Object.fromEntries(this.uniqIndex.map((k) => [this.mapColumnName(k), keyObj[k]]));
146
- } else return null;
143
+ if (Array.isArray(this.uniqIndex)) if (typeof key === "object") query = this.formatKeyToQuery(key);
144
+ else return null;
147
145
  else query = this.formatKeyToQuery(key);
148
146
  let qb = executor.selectFrom(this.name).selectAll();
149
147
  for (const [k, v] of Object.entries(query)) {
@@ -172,17 +170,14 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
172
170
  const updatesObj = updates;
173
171
  lookupKey = Object.fromEntries(this.uniqIndex.map((k) => [k, updatesObj[k]]));
174
172
  }
175
- const existing = await SqliteTable.prototype._get.call(this, lookupKey, context);
176
- if (!existing) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
177
173
  let query;
178
- if (Array.isArray(this.uniqIndex)) {
179
- const keyObj = typeof lookupKey === "object" ? lookupKey : existing;
180
- query = Object.fromEntries(this.uniqIndex.map((k) => [this.mapColumnName(k), keyObj[k]]));
181
- } else query = this.formatKeyToQuery(key);
174
+ if (Array.isArray(this.uniqIndex)) query = this.formatKeyToQuery(lookupKey);
175
+ else query = this.formatKeyToQuery(key);
182
176
  const updateAttrs = { ...updates };
183
177
  if (Array.isArray(this.uniqIndex)) for (const k of this.uniqIndex) delete updateAttrs[k];
184
178
  else delete updateAttrs[this.primaryKey];
185
179
  if (this.syncBalance) delete updateAttrs.tokens;
180
+ let merged;
186
181
  if (Object.keys(updateAttrs).length > 0) {
187
182
  const serialized = this.serializeForDb(updateAttrs);
188
183
  let qb = executor.updateTable(this.name).set(serialized);
@@ -190,17 +185,34 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
190
185
  if (v === void 0) continue;
191
186
  qb = qb.where(k, "=", v);
192
187
  }
193
- await qb.execute();
188
+ const updatedRow = await qb.returningAll().executeTakeFirst();
189
+ if (!updatedRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
190
+ merged = {
191
+ ...this.deserializeFromDb(updatedRow),
192
+ ...updateAttrs
193
+ };
194
+ } else {
195
+ let qb = executor.selectFrom(this.name).selectAll();
196
+ for (const [k, v] of Object.entries(query)) {
197
+ if (v === void 0) continue;
198
+ qb = qb.where(k, "=", v);
199
+ }
200
+ const existingRow = await qb.executeTakeFirst();
201
+ if (!existingRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
202
+ merged = this.deserializeFromDb(existingRow);
194
203
  }
195
- const merged = {
196
- ...existing,
197
- ...updateAttrs
198
- };
199
- if (this.syncBalance && updates.tokens) merged.tokens = await this.balanceTable.updateBalance({
204
+ if (this.syncBalance) if (updates.tokens) merged.tokens = await this.balanceTable.updateBalance({
200
205
  address: merged.address,
201
206
  tokens: updates.tokens,
202
207
  context: updates.context
203
208
  }, context);
209
+ else {
210
+ const balance = await this.balanceTable.getBalance(merged.address, context);
211
+ merged.tokens = {
212
+ ...merged.tokens || {},
213
+ ...balance
214
+ };
215
+ }
204
216
  return merged;
205
217
  }
206
218
  async _reset(_context) {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ocap/statedb-sqlite",
3
3
  "description": "OCAP statedb adapter that uses SQLite as backend",
4
- "version": "1.30.24",
4
+ "version": "1.30.26",
5
5
  "author": "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)",
6
6
  "bugs": {
7
7
  "url": "https://github.com/ArcBlock/blockchain/issues",
@@ -13,7 +13,9 @@
13
13
  "contributors": [
14
14
  "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"
15
15
  ],
16
- "devDependencies": {},
16
+ "devDependencies": {
17
+ "@ocap/statedb-test": "1.30.26"
18
+ },
17
19
  "homepage": "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
18
20
  "keywords": [
19
21
  "ocap",
@@ -61,10 +63,10 @@
61
63
  "clean": "rm -rf lib esm"
62
64
  },
63
65
  "dependencies": {
64
- "@ocap/state": "1.30.24",
65
- "@ocap/statedb": "1.30.24",
66
- "@ocap/types": "1.30.24",
67
- "@ocap/util": "1.30.24",
66
+ "@ocap/state": "1.30.26",
67
+ "@ocap/statedb": "1.30.26",
68
+ "@ocap/types": "1.30.26",
69
+ "@ocap/util": "1.30.26",
68
70
  "better-sqlite3": "^11.8.1",
69
71
  "kysely": "^0.28.14",
70
72
  "kysely-bun-sqlite": "^0.4.0",