@ocap/util 1.31.7 → 1.31.9

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.
@@ -0,0 +1,47 @@
1
+ //#region src/sql-timing.d.ts
2
+ /**
3
+ * SQLite execution time, attributed to whoever asked for it (#1891).
4
+ *
5
+ * `@ocap/gql` (while its slow-request log is on) runs every root field call inside an `AsyncLocalStorage` whose store
6
+ * is an `ISqlTimingSink`, and publishes that storage under `globalThis[SQL_TIMING_KEY]`. The SQLite backends
7
+ * (`@ocap/indexdb-sqlite`, `@ocap/statedb-sqlite`) pass every Kysely connection they open through
8
+ * `instrumentSqlTiming`, which adds the synchronous duration of each `executeQuery` call to the sink current at that
9
+ * moment. better-sqlite3 and bun:sqlite run the whole statement (prepare, every step, row objects) inside that call,
10
+ * so the sum is the field's SQLite time no matter how many `await`s come before the query: Kysely itself awaits its
11
+ * connection mutex before every statement, so the query never runs in the resolver's first synchronous segment.
12
+ *
13
+ * The key is a registered symbol, so separately bundled copies of these packages still meet. Without a published
14
+ * storage (logging off, or no `AsyncLocalStorage` on the runtime) the per-statement cost is one global property read.
15
+ */
16
+ declare const SQL_TIMING_KEY: unique symbol;
17
+ /**
18
+ * `globalThis[SQL_TIMING_BACKEND_KEY] === true` once any connection in the process is timed, so `@ocap/gql` reports
19
+ * SQL time only where a timed backend exists (not, e.g., on the untimed Durable Object backend).
20
+ */
21
+ declare const SQL_TIMING_BACKEND_KEY: unique symbol;
22
+ interface ISqlTimingSink {
23
+ /** Sum of the synchronous `executeQuery` time of the statements run in this context, ms. */
24
+ sqlMs: number;
25
+ /** Number of statements. */
26
+ sqlQueries: number;
27
+ /** Set by the owner when it has read the sink; later statements (work that outlived it) are not added. */
28
+ closed?: boolean;
29
+ }
30
+ /** The part of `AsyncLocalStorage` the backends need. */
31
+ interface ISqlTimingContext {
32
+ getStore(): ISqlTimingSink | undefined;
33
+ }
34
+ /** The sink of the current async context, if a timing context is published and the sink is still open. */
35
+ declare function currentSqlTimingSink(): ISqlTimingSink | undefined;
36
+ interface IQueryConnection {
37
+ executeQuery(...args: any[]): unknown;
38
+ }
39
+ /**
40
+ * Time the synchronous part of every `executeQuery` call on `connection` (a Kysely `DatabaseConnection`) into the
41
+ * current sink. Patches the instance in place, so connection identity is kept; idempotent. Meant for drivers whose
42
+ * `executeQuery` runs the statement synchronously and returns a settled promise (Kysely's `SqliteDialect` over
43
+ * better-sqlite3, `kysely-bun-sqlite`).
44
+ */
45
+ declare function instrumentSqlTiming<T extends IQueryConnection>(connection: T): T;
46
+ //#endregion
47
+ export { ISqlTimingContext, ISqlTimingSink, SQL_TIMING_BACKEND_KEY, SQL_TIMING_KEY, currentSqlTimingSink, instrumentSqlTiming };
@@ -0,0 +1,58 @@
1
+ //#region src/sql-timing.ts
2
+ /**
3
+ * SQLite execution time, attributed to whoever asked for it (#1891).
4
+ *
5
+ * `@ocap/gql` (while its slow-request log is on) runs every root field call inside an `AsyncLocalStorage` whose store
6
+ * is an `ISqlTimingSink`, and publishes that storage under `globalThis[SQL_TIMING_KEY]`. The SQLite backends
7
+ * (`@ocap/indexdb-sqlite`, `@ocap/statedb-sqlite`) pass every Kysely connection they open through
8
+ * `instrumentSqlTiming`, which adds the synchronous duration of each `executeQuery` call to the sink current at that
9
+ * moment. better-sqlite3 and bun:sqlite run the whole statement (prepare, every step, row objects) inside that call,
10
+ * so the sum is the field's SQLite time no matter how many `await`s come before the query: Kysely itself awaits its
11
+ * connection mutex before every statement, so the query never runs in the resolver's first synchronous segment.
12
+ *
13
+ * The key is a registered symbol, so separately bundled copies of these packages still meet. Without a published
14
+ * storage (logging off, or no `AsyncLocalStorage` on the runtime) the per-statement cost is one global property read.
15
+ */
16
+ const SQL_TIMING_KEY = Symbol.for("@ocap/sql-timing");
17
+ /**
18
+ * `globalThis[SQL_TIMING_BACKEND_KEY] === true` once any connection in the process is timed, so `@ocap/gql` reports
19
+ * SQL time only where a timed backend exists (not, e.g., on the untimed Durable Object backend).
20
+ */
21
+ const SQL_TIMING_BACKEND_KEY = Symbol.for("@ocap/sql-timing/backend");
22
+ const INSTRUMENTED = Symbol.for("@ocap/sql-timing/instrumented");
23
+ const now = typeof performance !== "undefined" && typeof performance.now === "function" ? () => performance.now() : () => Date.now();
24
+ /** The sink of the current async context, if a timing context is published and the sink is still open. */
25
+ function currentSqlTimingSink() {
26
+ const ctx = globalThis[SQL_TIMING_KEY];
27
+ if (ctx === void 0) return void 0;
28
+ const sink = ctx.getStore();
29
+ return sink !== void 0 && sink.closed !== true ? sink : void 0;
30
+ }
31
+ /**
32
+ * Time the synchronous part of every `executeQuery` call on `connection` (a Kysely `DatabaseConnection`) into the
33
+ * current sink. Patches the instance in place, so connection identity is kept; idempotent. Meant for drivers whose
34
+ * `executeQuery` runs the statement synchronously and returns a settled promise (Kysely's `SqliteDialect` over
35
+ * better-sqlite3, `kysely-bun-sqlite`).
36
+ */
37
+ function instrumentSqlTiming(connection) {
38
+ const c = connection;
39
+ if (c[INSTRUMENTED]) return connection;
40
+ const original = connection.executeQuery;
41
+ c.executeQuery = function executeQueryTimed(...args) {
42
+ const sink = currentSqlTimingSink();
43
+ if (sink === void 0) return original.apply(this, args);
44
+ const t = now();
45
+ try {
46
+ return original.apply(this, args);
47
+ } finally {
48
+ sink.sqlMs += now() - t;
49
+ sink.sqlQueries += 1;
50
+ }
51
+ };
52
+ Object.defineProperty(c, INSTRUMENTED, { value: true });
53
+ globalThis[SQL_TIMING_BACKEND_KEY] = true;
54
+ return connection;
55
+ }
56
+
57
+ //#endregion
58
+ export { SQL_TIMING_BACKEND_KEY, SQL_TIMING_KEY, currentSqlTimingSink, instrumentSqlTiming };
@@ -0,0 +1,62 @@
1
+
2
+ //#region src/sql-timing.ts
3
+ /**
4
+ * SQLite execution time, attributed to whoever asked for it (#1891).
5
+ *
6
+ * `@ocap/gql` (while its slow-request log is on) runs every root field call inside an `AsyncLocalStorage` whose store
7
+ * is an `ISqlTimingSink`, and publishes that storage under `globalThis[SQL_TIMING_KEY]`. The SQLite backends
8
+ * (`@ocap/indexdb-sqlite`, `@ocap/statedb-sqlite`) pass every Kysely connection they open through
9
+ * `instrumentSqlTiming`, which adds the synchronous duration of each `executeQuery` call to the sink current at that
10
+ * moment. better-sqlite3 and bun:sqlite run the whole statement (prepare, every step, row objects) inside that call,
11
+ * so the sum is the field's SQLite time no matter how many `await`s come before the query: Kysely itself awaits its
12
+ * connection mutex before every statement, so the query never runs in the resolver's first synchronous segment.
13
+ *
14
+ * The key is a registered symbol, so separately bundled copies of these packages still meet. Without a published
15
+ * storage (logging off, or no `AsyncLocalStorage` on the runtime) the per-statement cost is one global property read.
16
+ */
17
+ const SQL_TIMING_KEY = Symbol.for("@ocap/sql-timing");
18
+ /**
19
+ * `globalThis[SQL_TIMING_BACKEND_KEY] === true` once any connection in the process is timed, so `@ocap/gql` reports
20
+ * SQL time only where a timed backend exists (not, e.g., on the untimed Durable Object backend).
21
+ */
22
+ const SQL_TIMING_BACKEND_KEY = Symbol.for("@ocap/sql-timing/backend");
23
+ const INSTRUMENTED = Symbol.for("@ocap/sql-timing/instrumented");
24
+ const now = typeof performance !== "undefined" && typeof performance.now === "function" ? () => performance.now() : () => Date.now();
25
+ /** The sink of the current async context, if a timing context is published and the sink is still open. */
26
+ function currentSqlTimingSink() {
27
+ const ctx = globalThis[SQL_TIMING_KEY];
28
+ if (ctx === void 0) return void 0;
29
+ const sink = ctx.getStore();
30
+ return sink !== void 0 && sink.closed !== true ? sink : void 0;
31
+ }
32
+ /**
33
+ * Time the synchronous part of every `executeQuery` call on `connection` (a Kysely `DatabaseConnection`) into the
34
+ * current sink. Patches the instance in place, so connection identity is kept; idempotent. Meant for drivers whose
35
+ * `executeQuery` runs the statement synchronously and returns a settled promise (Kysely's `SqliteDialect` over
36
+ * better-sqlite3, `kysely-bun-sqlite`).
37
+ */
38
+ function instrumentSqlTiming(connection) {
39
+ const c = connection;
40
+ if (c[INSTRUMENTED]) return connection;
41
+ const original = connection.executeQuery;
42
+ c.executeQuery = function executeQueryTimed(...args) {
43
+ const sink = currentSqlTimingSink();
44
+ if (sink === void 0) return original.apply(this, args);
45
+ const t = now();
46
+ try {
47
+ return original.apply(this, args);
48
+ } finally {
49
+ sink.sqlMs += now() - t;
50
+ sink.sqlQueries += 1;
51
+ }
52
+ };
53
+ Object.defineProperty(c, INSTRUMENTED, { value: true });
54
+ globalThis[SQL_TIMING_BACKEND_KEY] = true;
55
+ return connection;
56
+ }
57
+
58
+ //#endregion
59
+ exports.SQL_TIMING_BACKEND_KEY = SQL_TIMING_BACKEND_KEY;
60
+ exports.SQL_TIMING_KEY = SQL_TIMING_KEY;
61
+ exports.currentSqlTimingSink = currentSqlTimingSink;
62
+ exports.instrumentSqlTiming = instrumentSqlTiming;
@@ -0,0 +1,47 @@
1
+ //#region src/sql-timing.d.ts
2
+ /**
3
+ * SQLite execution time, attributed to whoever asked for it (#1891).
4
+ *
5
+ * `@ocap/gql` (while its slow-request log is on) runs every root field call inside an `AsyncLocalStorage` whose store
6
+ * is an `ISqlTimingSink`, and publishes that storage under `globalThis[SQL_TIMING_KEY]`. The SQLite backends
7
+ * (`@ocap/indexdb-sqlite`, `@ocap/statedb-sqlite`) pass every Kysely connection they open through
8
+ * `instrumentSqlTiming`, which adds the synchronous duration of each `executeQuery` call to the sink current at that
9
+ * moment. better-sqlite3 and bun:sqlite run the whole statement (prepare, every step, row objects) inside that call,
10
+ * so the sum is the field's SQLite time no matter how many `await`s come before the query: Kysely itself awaits its
11
+ * connection mutex before every statement, so the query never runs in the resolver's first synchronous segment.
12
+ *
13
+ * The key is a registered symbol, so separately bundled copies of these packages still meet. Without a published
14
+ * storage (logging off, or no `AsyncLocalStorage` on the runtime) the per-statement cost is one global property read.
15
+ */
16
+ declare const SQL_TIMING_KEY: unique symbol;
17
+ /**
18
+ * `globalThis[SQL_TIMING_BACKEND_KEY] === true` once any connection in the process is timed, so `@ocap/gql` reports
19
+ * SQL time only where a timed backend exists (not, e.g., on the untimed Durable Object backend).
20
+ */
21
+ declare const SQL_TIMING_BACKEND_KEY: unique symbol;
22
+ interface ISqlTimingSink {
23
+ /** Sum of the synchronous `executeQuery` time of the statements run in this context, ms. */
24
+ sqlMs: number;
25
+ /** Number of statements. */
26
+ sqlQueries: number;
27
+ /** Set by the owner when it has read the sink; later statements (work that outlived it) are not added. */
28
+ closed?: boolean;
29
+ }
30
+ /** The part of `AsyncLocalStorage` the backends need. */
31
+ interface ISqlTimingContext {
32
+ getStore(): ISqlTimingSink | undefined;
33
+ }
34
+ /** The sink of the current async context, if a timing context is published and the sink is still open. */
35
+ declare function currentSqlTimingSink(): ISqlTimingSink | undefined;
36
+ interface IQueryConnection {
37
+ executeQuery(...args: any[]): unknown;
38
+ }
39
+ /**
40
+ * Time the synchronous part of every `executeQuery` call on `connection` (a Kysely `DatabaseConnection`) into the
41
+ * current sink. Patches the instance in place, so connection identity is kept; idempotent. Meant for drivers whose
42
+ * `executeQuery` runs the statement synchronously and returns a settled promise (Kysely's `SqliteDialect` over
43
+ * better-sqlite3, `kysely-bun-sqlite`).
44
+ */
45
+ declare function instrumentSqlTiming<T extends IQueryConnection>(connection: T): T;
46
+ //#endregion
47
+ export { ISqlTimingContext, ISqlTimingSink, SQL_TIMING_BACKEND_KEY, SQL_TIMING_KEY, currentSqlTimingSink, instrumentSqlTiming };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ocap/util",
3
- "version": "1.31.7",
3
+ "version": "1.31.9",
4
4
  "type": "module",
5
5
  "description": "utils shared across multiple forge js libs, works in both node.js and browser",
6
6
  "keywords": [
@@ -12,7 +12,7 @@
12
12
  "access": "public"
13
13
  },
14
14
  "dependencies": {
15
- "@ocap/types": "1.31.7",
15
+ "@ocap/types": "1.31.9",
16
16
  "@types/bn.js": "^5.2.0",
17
17
  "base64-url": "^2.3.3",
18
18
  "bn.js": "5.2.3",