@rocicorp/zero 1.10.0-canary.19 → 1.10.0-canary.20
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/out/replicache/src/btree/read.d.ts +12 -1
- package/out/replicache/src/btree/read.d.ts.map +1 -1
- package/out/replicache/src/btree/read.js +24 -12
- package/out/replicache/src/btree/read.js.map +1 -1
- package/out/replicache/src/db/write.js.map +1 -1
- package/out/replicache/src/kv/expo-sqlite/store.d.ts.map +1 -1
- package/out/replicache/src/kv/expo-sqlite/store.js +27 -4
- package/out/replicache/src/kv/expo-sqlite/store.js.map +1 -1
- package/out/replicache/src/kv/sqlite-store.d.ts +11 -0
- package/out/replicache/src/kv/sqlite-store.d.ts.map +1 -1
- package/out/replicache/src/kv/sqlite-store.js +43 -3
- package/out/replicache/src/kv/sqlite-store.js.map +1 -1
- package/out/replicache/src/replicache-impl.d.ts.map +1 -1
- package/out/replicache/src/replicache-impl.js +10 -0
- package/out/replicache/src/replicache-impl.js.map +1 -1
- package/out/replicache/src/transactions.d.ts.map +1 -1
- package/out/replicache/src/transactions.js +1 -1
- package/out/replicache/src/transactions.js.map +1 -1
- package/out/shared/src/error.d.ts +11 -0
- package/out/shared/src/error.d.ts.map +1 -1
- package/out/shared/src/error.js +35 -1
- package/out/shared/src/error.js.map +1 -1
- package/out/shared/src/hash.d.ts.map +1 -1
- package/out/shared/src/hash.js +105 -10
- package/out/shared/src/hash.js.map +1 -1
- package/out/shared/src/map.d.ts +7 -2
- package/out/shared/src/map.d.ts.map +1 -1
- package/out/shared/src/map.js.map +1 -1
- package/out/zero/package.js +2 -3
- package/out/zero/package.js.map +1 -1
- package/out/zero-cache/src/config/zero-config.d.ts +19 -2
- package/out/zero-cache/src/config/zero-config.d.ts.map +1 -1
- package/out/zero-cache/src/config/zero-config.js +86 -27
- package/out/zero-cache/src/config/zero-config.js.map +1 -1
- package/out/zero-cache/src/db/create.d.ts.map +1 -1
- package/out/zero-cache/src/db/create.js +4 -1
- package/out/zero-cache/src/db/create.js.map +1 -1
- package/out/zero-cache/src/db/index-predicate.d.ts +4 -0
- package/out/zero-cache/src/db/index-predicate.d.ts.map +1 -0
- package/out/zero-cache/src/db/index-predicate.js +46 -0
- package/out/zero-cache/src/db/index-predicate.js.map +1 -0
- package/out/zero-cache/src/db/lite-tables.d.ts +10 -2
- package/out/zero-cache/src/db/lite-tables.d.ts.map +1 -1
- package/out/zero-cache/src/db/lite-tables.js +8 -3
- package/out/zero-cache/src/db/lite-tables.js.map +1 -1
- package/out/zero-cache/src/db/specs.d.ts +41 -0
- package/out/zero-cache/src/db/specs.d.ts.map +1 -1
- package/out/zero-cache/src/db/specs.js +30 -3
- package/out/zero-cache/src/db/specs.js.map +1 -1
- package/out/zero-cache/src/server/change-streamer.d.ts.map +1 -1
- package/out/zero-cache/src/server/change-streamer.js +2 -1
- package/out/zero-cache/src/server/change-streamer.js.map +1 -1
- package/out/zero-cache/src/server/replicator.d.ts.map +1 -1
- package/out/zero-cache/src/server/replicator.js +6 -2
- package/out/zero-cache/src/server/replicator.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/change-source.d.ts +11 -1
- package/out/zero-cache/src/services/change-source/pg/change-source.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/change-source.js +21 -2
- package/out/zero-cache/src/services/change-source/pg/change-source.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/initial-sync.d.ts +1 -0
- package/out/zero-cache/src/services/change-source/pg/initial-sync.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/initial-sync.js +7 -6
- package/out/zero-cache/src/services/change-source/pg/initial-sync.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/ddl.d.ts +1513 -229
- package/out/zero-cache/src/services/change-source/pg/schema/ddl.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/ddl.js +2 -2
- package/out/zero-cache/src/services/change-source/pg/schema/ddl.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/index-predicate.d.ts +19 -0
- package/out/zero-cache/src/services/change-source/pg/schema/index-predicate.d.ts.map +1 -0
- package/out/zero-cache/src/services/change-source/pg/schema/index-predicate.js +581 -0
- package/out/zero-cache/src/services/change-source/pg/schema/index-predicate.js.map +1 -0
- package/out/zero-cache/src/services/change-source/pg/schema/init.d.ts +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/init.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/init.js +15 -6
- package/out/zero-cache/src/services/change-source/pg/schema/init.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/published.d.ts +137 -20
- package/out/zero-cache/src/services/change-source/pg/schema/published.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/published.js +82 -13
- package/out/zero-cache/src/services/change-source/pg/schema/published.js.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/shard.d.ts +128 -21
- package/out/zero-cache/src/services/change-source/pg/schema/shard.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/pg/schema/shard.js +5 -5
- package/out/zero-cache/src/services/change-source/pg/schema/shard.js.map +1 -1
- package/out/zero-cache/src/services/change-source/protocol/current/data.d.ts +2 -0
- package/out/zero-cache/src/services/change-source/protocol/current/data.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-source/protocol/current/downstream.d.ts +3 -0
- package/out/zero-cache/src/services/change-source/protocol/current/downstream.d.ts.map +1 -1
- package/out/zero-cache/src/services/change-streamer/change-streamer.d.ts +1 -0
- package/out/zero-cache/src/services/change-streamer/change-streamer.d.ts.map +1 -1
- package/out/zero-cache/src/services/litestream/commands.d.ts.map +1 -1
- package/out/zero-cache/src/services/litestream/commands.js +8 -3
- package/out/zero-cache/src/services/litestream/commands.js.map +1 -1
- package/out/zero-cache/src/services/litestream/config-v5.yml +15 -1
- package/out/zero-cache/src/services/litestream/litestream-checkpointer.js +131 -0
- package/out/zero-cache/src/services/litestream/litestream-checkpointer.js.map +1 -0
- package/out/zero-cache/src/services/litestream/litestream-controller.d.ts +70 -0
- package/out/zero-cache/src/services/litestream/litestream-controller.d.ts.map +1 -0
- package/out/zero-cache/src/services/litestream/litestream-controller.js +101 -0
- package/out/zero-cache/src/services/litestream/litestream-controller.js.map +1 -0
- package/out/zero-cache/src/services/replicator/change-processor.d.ts.map +1 -1
- package/out/zero-cache/src/services/replicator/change-processor.js +16 -16
- package/out/zero-cache/src/services/replicator/change-processor.js.map +1 -1
- package/out/zero-cache/src/services/replicator/incremental-sync.d.ts.map +1 -1
- package/out/zero-cache/src/services/replicator/incremental-sync.js +1 -0
- package/out/zero-cache/src/services/replicator/incremental-sync.js.map +1 -1
- package/out/zero-cache/src/services/replicator/write-worker-client.d.ts +27 -2
- package/out/zero-cache/src/services/replicator/write-worker-client.d.ts.map +1 -1
- package/out/zero-cache/src/services/replicator/write-worker-client.js +3 -2
- package/out/zero-cache/src/services/replicator/write-worker-client.js.map +1 -1
- package/out/zero-cache/src/services/replicator/write-worker.js +24 -5
- package/out/zero-cache/src/services/replicator/write-worker.js.map +1 -1
- package/out/zero-cache/src/workers/replicator.d.ts +1 -0
- package/out/zero-cache/src/workers/replicator.d.ts.map +1 -1
- package/out/zero-cache/src/workers/replicator.js +4 -2
- package/out/zero-cache/src/workers/replicator.js.map +1 -1
- package/out/zero-client/src/client/connection-manager.d.ts.map +1 -1
- package/out/zero-client/src/client/connection-manager.js +46 -0
- package/out/zero-client/src/client/connection-manager.js.map +1 -1
- package/out/zero-client/src/client/context.d.ts +15 -0
- package/out/zero-client/src/client/context.d.ts.map +1 -1
- package/out/zero-client/src/client/context.js +44 -0
- package/out/zero-client/src/client/context.js.map +1 -1
- package/out/zero-client/src/client/inspector/lazy-inspector.js +2 -2
- package/out/zero-client/src/client/inspector/lazy-inspector.js.map +1 -1
- package/out/zero-client/src/client/ivm-branch.js.map +1 -1
- package/out/zero-client/src/client/version.js +1 -1
- package/out/zero-client/src/client/zero-rep.d.ts.map +1 -1
- package/out/zero-client/src/client/zero-rep.js +2 -1
- package/out/zero-client/src/client/zero-rep.js.map +1 -1
- package/out/zero-client/src/client/zero.d.ts.map +1 -1
- package/out/zero-client/src/client/zero.js +60 -19
- package/out/zero-client/src/client/zero.js.map +1 -1
- package/out/zql/src/ivm/array-view.d.ts.map +1 -1
- package/out/zql/src/ivm/array-view.js +5 -3
- package/out/zql/src/ivm/array-view.js.map +1 -1
- package/out/zql/src/ivm/data.d.ts.map +1 -1
- package/out/zql/src/ivm/data.js +8 -3
- package/out/zql/src/ivm/data.js.map +1 -1
- package/out/zql/src/ivm/deferred-input.d.ts +44 -0
- package/out/zql/src/ivm/deferred-input.d.ts.map +1 -0
- package/out/zql/src/ivm/deferred-input.js +88 -0
- package/out/zql/src/ivm/deferred-input.js.map +1 -0
- package/out/zql/src/ivm/memory-source.d.ts.map +1 -1
- package/out/zql/src/ivm/memory-source.js +5 -10
- package/out/zql/src/ivm/memory-source.js.map +1 -1
- package/out/zql/src/ivm/view-apply-change.js +6 -1
- package/out/zql/src/ivm/view-apply-change.js.map +1 -1
- package/out/zql/src/query/query-delegate-base.d.ts +6 -0
- package/out/zql/src/query/query-delegate-base.d.ts.map +1 -1
- package/out/zql/src/query/query-delegate-base.js +73 -10
- package/out/zql/src/query/query-delegate-base.js.map +1 -1
- package/out/zql/src/query/query-delegate.d.ts +22 -0
- package/out/zql/src/query/query-delegate.d.ts.map +1 -1
- package/out/zqlite/src/query-builder.d.ts.map +1 -1
- package/out/zqlite/src/query-builder.js +2 -1
- package/out/zqlite/src/query-builder.js.map +1 -1
- package/out/zqlite/src/sqlite-stat-fanout.d.ts.map +1 -1
- package/out/zqlite/src/sqlite-stat-fanout.js +1 -0
- package/out/zqlite/src/sqlite-stat-fanout.js.map +1 -1
- package/out/zqlite/src/table-source.d.ts +1 -1
- package/out/zqlite/src/table-source.d.ts.map +1 -1
- package/out/zqlite/src/table-source.js +2 -1
- package/out/zqlite/src/table-source.js.map +1 -1
- package/package.json +2 -3
|
@@ -2,6 +2,7 @@ import { hashOfNameAndArgs } from "../../../zero-protocol/src/query-hash.js";
|
|
|
2
2
|
import { asQueryInternals } from "./query-internals.js";
|
|
3
3
|
import { buildPipeline } from "../builder/builder.js";
|
|
4
4
|
import { ArrayView } from "../ivm/array-view.js";
|
|
5
|
+
import { DeferredInput } from "../ivm/deferred-input.js";
|
|
5
6
|
import { MemoryStorage } from "../ivm/memory-storage.js";
|
|
6
7
|
import "./ttl.js";
|
|
7
8
|
import { resolver } from "@rocicorp/resolver";
|
|
@@ -114,6 +115,16 @@ var QueryDelegateBase = class {
|
|
|
114
115
|
* Default implementation is a no-op.
|
|
115
116
|
*/
|
|
116
117
|
assertValidRunOptions(_options) {}
|
|
118
|
+
/**
|
|
119
|
+
* Default: pipelines can always be built immediately. Override (together
|
|
120
|
+
* with `onPipelinesReady`) to defer pipeline construction.
|
|
121
|
+
*/
|
|
122
|
+
get pipelinesReady() {
|
|
123
|
+
return true;
|
|
124
|
+
}
|
|
125
|
+
onPipelinesReady(_cb) {
|
|
126
|
+
throw new Error("onPipelinesReady called on a delegate whose pipelines are always ready");
|
|
127
|
+
}
|
|
117
128
|
};
|
|
118
129
|
async function runImpl(query, delegate, options) {
|
|
119
130
|
delegate.assertValidRunOptions(options);
|
|
@@ -159,9 +170,18 @@ function materializeImpl(query, delegate, factory = arrayViewFactory, options) {
|
|
|
159
170
|
const queryHash = qi.hash();
|
|
160
171
|
const queryID = customQueryID ? hashOfNameAndArgs(customQueryID.name, customQueryID.args) : queryHash;
|
|
161
172
|
const queryCompleteResolver = resolver();
|
|
162
|
-
|
|
163
|
-
let
|
|
173
|
+
const deferPipeline = !delegate.pipelinesReady;
|
|
174
|
+
let attached = !deferPipeline;
|
|
175
|
+
let gotQueries = delegate.defaultQueryComplete;
|
|
176
|
+
let queryComplete = attached && gotQueries;
|
|
164
177
|
const updateTTL = customQueryID ? (newTTL) => delegate.updateCustomQuery(customQueryID, newTTL) : (newTTL) => delegate.updateServerQuery(ast, newTTL);
|
|
178
|
+
const maybeResolveComplete = () => {
|
|
179
|
+
if (attached && gotQueries && queryComplete !== true) {
|
|
180
|
+
delegate.addMetric("query-materialization-end-to-end", performance.now() - t0, queryID, ast);
|
|
181
|
+
queryComplete = true;
|
|
182
|
+
queryCompleteResolver.resolve(true);
|
|
183
|
+
}
|
|
184
|
+
};
|
|
165
185
|
const gotCallback = (got, error) => {
|
|
166
186
|
if (error) {
|
|
167
187
|
queryCompleteResolver.reject(error);
|
|
@@ -169,29 +189,72 @@ function materializeImpl(query, delegate, factory = arrayViewFactory, options) {
|
|
|
169
189
|
return;
|
|
170
190
|
}
|
|
171
191
|
if (got) {
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
endToEndMetricRecorded = true;
|
|
175
|
-
}
|
|
176
|
-
queryComplete = true;
|
|
177
|
-
queryCompleteResolver.resolve(true);
|
|
192
|
+
gotQueries = true;
|
|
193
|
+
maybeResolveComplete();
|
|
178
194
|
}
|
|
179
195
|
};
|
|
180
196
|
let removeCommitObserver;
|
|
197
|
+
let removePendingAttach;
|
|
181
198
|
const onDestroy = () => {
|
|
199
|
+
removePendingAttach?.();
|
|
200
|
+
removePendingAttach = void 0;
|
|
182
201
|
input.destroy();
|
|
183
202
|
removeCommitObserver?.();
|
|
184
203
|
removeAddedQuery();
|
|
185
204
|
};
|
|
186
205
|
const t0 = performance.now();
|
|
187
206
|
const removeAddedQuery = customQueryID ? delegate.addCustomQuery(ast, customQueryID, ttl, gotCallback) : delegate.addServerQuery(ast, ttl, gotCallback);
|
|
188
|
-
const
|
|
207
|
+
const deferred = deferPipeline ? newDeferredInput(ast, delegate, queryID) : void 0;
|
|
208
|
+
const input = deferred ?? buildPipeline(ast, delegate, queryID);
|
|
189
209
|
const view = delegate.batchViewUpdates(() => (factory ?? arrayViewFactory)(query, input, format, onDestroy, (cb) => {
|
|
190
210
|
removeCommitObserver = delegate.onTransactionCommit(cb);
|
|
191
211
|
}, queryComplete || queryCompleteResolver.promise, updateTTL));
|
|
192
|
-
delegate.addMetric("query-materialization-client", performance.now() - t0, queryID);
|
|
212
|
+
if (!deferred) delegate.addMetric("query-materialization-client", performance.now() - t0, queryID);
|
|
213
|
+
else removePendingAttach = delegate.onPipelinesReady(() => {
|
|
214
|
+
removePendingAttach = void 0;
|
|
215
|
+
if (deferred.destroyed) return;
|
|
216
|
+
const t1 = performance.now();
|
|
217
|
+
try {
|
|
218
|
+
deferred.attach();
|
|
219
|
+
} catch (e) {
|
|
220
|
+
const error = {
|
|
221
|
+
error: "app",
|
|
222
|
+
id: queryID,
|
|
223
|
+
name: customQueryID?.name ?? "",
|
|
224
|
+
message: e instanceof Error ? e.message : String(e)
|
|
225
|
+
};
|
|
226
|
+
queryComplete = error;
|
|
227
|
+
queryCompleteResolver.reject(error);
|
|
228
|
+
throw e;
|
|
229
|
+
}
|
|
230
|
+
attached = true;
|
|
231
|
+
delegate.addMetric("query-materialization-client", performance.now() - t1, queryID);
|
|
232
|
+
maybeResolveComplete();
|
|
233
|
+
});
|
|
193
234
|
return view;
|
|
194
235
|
}
|
|
236
|
+
/**
|
|
237
|
+
* Creates the placeholder input for a query whose pipeline cannot be built yet.
|
|
238
|
+
*
|
|
239
|
+
* `Input.getSchema()` is unconditional, so the placeholder needs the schema up
|
|
240
|
+
* front. It is captured by building a pipeline and immediately destroying it:
|
|
241
|
+
* building only connects to the sources, while the indexes and rows -- the
|
|
242
|
+
* expensive part this deferral exists to postpone -- are read on the first
|
|
243
|
+
* fetch. Measured at ~5us against ~500us for a single 100 row fetch.
|
|
244
|
+
*
|
|
245
|
+
* Building here also means a query that cannot be built at all (an unknown
|
|
246
|
+
* table, `not(exists())` on the client) still throws from `materialize()`,
|
|
247
|
+
* as it did before hydration was deferred.
|
|
248
|
+
*/
|
|
249
|
+
function newDeferredInput(ast, delegate, queryID) {
|
|
250
|
+
const build = () => buildPipeline(ast, delegate, queryID);
|
|
251
|
+
const probe = build();
|
|
252
|
+
try {
|
|
253
|
+
return new DeferredInput(probe.getSchema(), build);
|
|
254
|
+
} finally {
|
|
255
|
+
probe.destroy();
|
|
256
|
+
}
|
|
257
|
+
}
|
|
195
258
|
function arrayViewFactory(_query, input, format, onDestroy, onTransactionCommit, queryComplete, updateTTL) {
|
|
196
259
|
const v = new ArrayView(input, format, queryComplete, updateTTL);
|
|
197
260
|
v.onDestroy = onDestroy;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-delegate-base.js","names":[],"sources":["../../../../../zql/src/query/query-delegate-base.ts"],"sourcesContent":["import {resolver} from '@rocicorp/resolver';\nimport type {AST} from '../../../zero-protocol/src/ast.ts';\nimport type {ErroredQuery} from '../../../zero-protocol/src/custom-queries.ts';\nimport {hashOfNameAndArgs} from '../../../zero-protocol/src/query-hash.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport {buildPipeline} from '../builder/builder.ts';\nimport {ArrayView} from '../ivm/array-view.ts';\nimport type {FilterInput} from '../ivm/filter-operators.ts';\nimport {MemoryStorage} from '../ivm/memory-storage.ts';\nimport type {Input, InputBase, Storage} from '../ivm/operator.ts';\nimport type {Source, SourceInput} from '../ivm/source.ts';\nimport type {Format, ViewFactory} from '../ivm/view.ts';\nimport type {MetricMap} from './metrics-delegate.ts';\nimport type {CustomQueryID} from './named.ts';\nimport type {\n CommitListener,\n GotCallback,\n QueryDelegate,\n} from './query-delegate.ts';\nimport {asQueryInternals, type QueryInternals} from './query-internals.ts';\nimport type {\n HumanReadable,\n MaterializeOptions,\n PreloadOptions,\n Query,\n RunOptions,\n} from './query.ts';\nimport {DEFAULT_PRELOAD_TTL_MS, DEFAULT_TTL_MS, type TTL} from './ttl.ts';\nimport type {TypedView} from './typed-view.ts';\n\n/**\n * Base class that provides default implementations for common QueryDelegate methods.\n * Subclasses can override specific methods as needed.\n */\nexport abstract class QueryDelegateBase implements QueryDelegate {\n /**\n * Default implementation that just calls applyViewUpdates synchronously.\n * Override if you need custom batching behavior (e.g., SolidJS).\n */\n batchViewUpdates<T>(applyViewUpdates: () => T): T {\n return applyViewUpdates();\n }\n\n /**\n * Default implementation returns MemoryStorage.\n * Override if you need custom storage.\n */\n createStorage(): Storage {\n return new MemoryStorage();\n }\n\n /**\n * Default implementation calls materializeImpl.\n * Override if you need custom materialization behavior.\n */\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: undefined,\n options?: MaterializeOptions,\n ): TypedView<HumanReadable<TReturn>>;\n\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T;\n\n /**\n * Materialize a query into a custom view using a provided factory function.\n */\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T;\n\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T {\n return materializeImpl(query, this, factory, options);\n }\n\n /**\n * Default implementation calls runImpl.\n * Override if you need custom query execution (e.g., TestPGQueryDelegate).\n */\n run<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n options?: RunOptions,\n ): Promise<HumanReadable<TReturn>> {\n return runImpl(query, this, options);\n }\n\n /**\n * Default implementation calls preloadImpl.\n * Override if you need custom preload behavior.\n */\n preload<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n options?: PreloadOptions,\n ): {\n cleanup: () => void;\n complete: Promise<void>;\n } {\n return preloadImpl(query, this, options);\n }\n\n /**\n * Default no-op implementation for decorateSourceInput.\n * Override if you need to wrap or instrument source inputs.\n */\n decorateSourceInput(input: SourceInput, _queryID: string): Input {\n return input;\n }\n\n /**\n * Default no-op implementation for decorateInput.\n * Override if you need to wrap or instrument inputs.\n */\n decorateInput(input: Input, _name: string): Input {\n return input;\n }\n\n /**\n * Default no-op implementation for decorateFilterInput.\n * Override if you need to wrap or instrument filter inputs.\n */\n decorateFilterInput(input: FilterInput, _name: string): FilterInput {\n return input;\n }\n\n /**\n * Default no-op implementation for addEdge.\n * Override if you need to track graph edges (e.g., visualization).\n */\n addEdge(_source: InputBase, _dest: InputBase): void {\n // No-op\n }\n\n /**\n * Default no-op implementation for addMetric.\n * Override if you need to collect metrics.\n */\n addMetric<K extends keyof MetricMap>(\n _metric: K,\n _value: number,\n ..._args: MetricMap[K]\n ): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to track server queries (e.g., ZeroContext, test delegates).\n */\n addServerQuery(_ast: AST, _ttl: TTL, _gotCallback?: GotCallback): () => void {\n return () => {};\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to track custom queries (e.g., ZeroContext, test delegates).\n */\n addCustomQuery(\n _ast: AST,\n _customQueryID: CustomQueryID,\n _ttl: TTL,\n _gotCallback?: GotCallback,\n ): () => void {\n return () => {};\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to handle query updates.\n */\n updateServerQuery(_ast: AST, _ttl: TTL): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to handle custom query updates.\n */\n updateCustomQuery(_customQueryID: CustomQueryID, _ttl: TTL): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to flush query changes.\n */\n flushQueryChanges(): void {\n // No-op\n }\n\n /**\n * Called when a transaction commits. Override to add custom behavior.\n * Default implementation returns a no-op cleanup function.\n */\n onTransactionCommit(_cb: CommitListener): () => void {\n return () => {};\n }\n\n /**\n * Validates run options. Override to add custom validation.\n * Default implementation is a no-op.\n */\n assertValidRunOptions(_options?: RunOptions): void {\n // No-op\n }\n\n abstract readonly defaultQueryComplete: boolean;\n\n // BuilderDelegate methods - must be implemented\n abstract getSource(name: string): Source | undefined;\n}\n\n// oxlint-disable-next-line require-await\nexport async function runImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n options?: RunOptions,\n): Promise<HumanReadable<TReturn>> {\n delegate.assertValidRunOptions(options);\n const v: TypedView<HumanReadable<TReturn>> = materializeImpl(\n query,\n delegate,\n undefined,\n {\n ttl: options?.ttl,\n },\n );\n if (options?.type === 'complete') {\n return new Promise(resolve => {\n v.addListener((data, type) => {\n if (type === 'complete') {\n v.destroy();\n resolve(data as HumanReadable<TReturn>);\n } else if (type === 'error') {\n v.destroy();\n resolve(Promise.reject(data));\n }\n });\n });\n }\n\n options?.type satisfies 'unknown' | undefined;\n\n const ret = v.data;\n v.destroy();\n return ret;\n}\n\nexport function preloadImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n options?: PreloadOptions,\n): {\n cleanup: () => void;\n complete: Promise<void>;\n} {\n const qi = asQueryInternals(query);\n const ttl = options?.ttl ?? DEFAULT_PRELOAD_TTL_MS;\n const {resolve, promise: complete} = resolver<void>();\n const {customQueryID, ast} = qi;\n if (customQueryID) {\n const cleanup = delegate.addCustomQuery(ast, customQueryID, ttl, got => {\n if (got) {\n resolve();\n }\n });\n return {\n cleanup,\n complete,\n };\n }\n\n const cleanup = delegate.addServerQuery(ast, ttl, got => {\n if (got) {\n resolve();\n }\n });\n return {\n cleanup,\n complete,\n };\n}\n\nexport function materializeImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n factory: ViewFactory<\n TTable,\n TSchema,\n TReturn,\n T\n // oxlint-disable-next-line no-explicit-any\n > = arrayViewFactory as any,\n options?: MaterializeOptions,\n): T {\n let ttl: TTL = options?.ttl ?? DEFAULT_TTL_MS;\n\n const qi = asQueryInternals(query);\n const {ast, format, customQueryID} = qi;\n const queryHash = qi.hash();\n\n const queryID = customQueryID\n ? hashOfNameAndArgs(customQueryID.name, customQueryID.args)\n : queryHash;\n const queryCompleteResolver = resolver<true>();\n let queryComplete: boolean | ErroredQuery = delegate.defaultQueryComplete;\n let endToEndMetricRecorded = false;\n const updateTTL = customQueryID\n ? (newTTL: TTL) => delegate.updateCustomQuery(customQueryID, newTTL)\n : (newTTL: TTL) => delegate.updateServerQuery(ast, newTTL);\n\n const gotCallback: GotCallback = (got, error) => {\n if (error) {\n queryCompleteResolver.reject(error);\n queryComplete = error;\n return;\n }\n\n if (got) {\n if (!endToEndMetricRecorded) {\n delegate.addMetric(\n 'query-materialization-end-to-end',\n performance.now() - t0,\n queryID,\n ast,\n );\n endToEndMetricRecorded = true;\n }\n queryComplete = true;\n queryCompleteResolver.resolve(true);\n }\n };\n\n let removeCommitObserver: (() => void) | undefined;\n const onDestroy = () => {\n input.destroy();\n removeCommitObserver?.();\n removeAddedQuery();\n };\n\n const t0 = performance.now();\n\n const removeAddedQuery = customQueryID\n ? delegate.addCustomQuery(ast, customQueryID, ttl, gotCallback)\n : delegate.addServerQuery(ast, ttl, gotCallback);\n\n const input = buildPipeline(ast, delegate, queryID);\n\n const view = delegate.batchViewUpdates(() =>\n (factory ?? arrayViewFactory)(\n query,\n input,\n format,\n onDestroy,\n cb => {\n removeCommitObserver = delegate.onTransactionCommit(cb);\n },\n queryComplete || queryCompleteResolver.promise,\n updateTTL,\n ),\n );\n\n delegate.addMetric(\n 'query-materialization-client',\n performance.now() - t0,\n queryID,\n );\n\n return view as T;\n}\n\nfunction arrayViewFactory<\n TTable extends string,\n TSchema extends Schema,\n TReturn,\n>(\n _query: QueryInternals<TTable, TSchema, TReturn>,\n input: Input,\n format: Format,\n onDestroy: () => void,\n onTransactionCommit: (cb: () => void) => void,\n queryComplete: true | ErroredQuery | Promise<true>,\n updateTTL: (ttl: TTL) => void,\n): TypedView<HumanReadable<TReturn>> {\n const v = new ArrayView<HumanReadable<TReturn>>(\n input,\n format,\n queryComplete,\n updateTTL,\n );\n v.onDestroy = onDestroy;\n onTransactionCommit(() => v.flush());\n return v;\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"query-delegate-base.js","names":[],"sources":["../../../../../zql/src/query/query-delegate-base.ts"],"sourcesContent":["import {resolver} from '@rocicorp/resolver';\nimport type {AST} from '../../../zero-protocol/src/ast.ts';\nimport type {ErroredQuery} from '../../../zero-protocol/src/custom-queries.ts';\nimport {hashOfNameAndArgs} from '../../../zero-protocol/src/query-hash.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport {buildPipeline} from '../builder/builder.ts';\nimport {ArrayView} from '../ivm/array-view.ts';\nimport {DeferredInput} from '../ivm/deferred-input.ts';\nimport type {FilterInput} from '../ivm/filter-operators.ts';\nimport {MemoryStorage} from '../ivm/memory-storage.ts';\nimport type {Input, InputBase, Storage} from '../ivm/operator.ts';\nimport type {Source, SourceInput} from '../ivm/source.ts';\nimport type {Format, ViewFactory} from '../ivm/view.ts';\nimport type {MetricMap} from './metrics-delegate.ts';\nimport type {CustomQueryID} from './named.ts';\nimport type {\n CommitListener,\n GotCallback,\n QueryDelegate,\n} from './query-delegate.ts';\nimport {asQueryInternals, type QueryInternals} from './query-internals.ts';\nimport type {\n HumanReadable,\n MaterializeOptions,\n PreloadOptions,\n Query,\n RunOptions,\n} from './query.ts';\nimport {DEFAULT_PRELOAD_TTL_MS, DEFAULT_TTL_MS, type TTL} from './ttl.ts';\nimport type {TypedView} from './typed-view.ts';\n\n/**\n * Base class that provides default implementations for common QueryDelegate methods.\n * Subclasses can override specific methods as needed.\n */\nexport abstract class QueryDelegateBase implements QueryDelegate {\n /**\n * Default implementation that just calls applyViewUpdates synchronously.\n * Override if you need custom batching behavior (e.g., SolidJS).\n */\n batchViewUpdates<T>(applyViewUpdates: () => T): T {\n return applyViewUpdates();\n }\n\n /**\n * Default implementation returns MemoryStorage.\n * Override if you need custom storage.\n */\n createStorage(): Storage {\n return new MemoryStorage();\n }\n\n /**\n * Default implementation calls materializeImpl.\n * Override if you need custom materialization behavior.\n */\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: undefined,\n options?: MaterializeOptions,\n ): TypedView<HumanReadable<TReturn>>;\n\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T;\n\n /**\n * Materialize a query into a custom view using a provided factory function.\n */\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T;\n\n materialize<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n >(\n query: Query<TTable, TSchema, TReturn>,\n factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n options?: MaterializeOptions,\n ): T {\n return materializeImpl(query, this, factory, options);\n }\n\n /**\n * Default implementation calls runImpl.\n * Override if you need custom query execution (e.g., TestPGQueryDelegate).\n */\n run<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n options?: RunOptions,\n ): Promise<HumanReadable<TReturn>> {\n return runImpl(query, this, options);\n }\n\n /**\n * Default implementation calls preloadImpl.\n * Override if you need custom preload behavior.\n */\n preload<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n >(\n query: Query<TTable, TSchema, TReturn>,\n options?: PreloadOptions,\n ): {\n cleanup: () => void;\n complete: Promise<void>;\n } {\n return preloadImpl(query, this, options);\n }\n\n /**\n * Default no-op implementation for decorateSourceInput.\n * Override if you need to wrap or instrument source inputs.\n */\n decorateSourceInput(input: SourceInput, _queryID: string): Input {\n return input;\n }\n\n /**\n * Default no-op implementation for decorateInput.\n * Override if you need to wrap or instrument inputs.\n */\n decorateInput(input: Input, _name: string): Input {\n return input;\n }\n\n /**\n * Default no-op implementation for decorateFilterInput.\n * Override if you need to wrap or instrument filter inputs.\n */\n decorateFilterInput(input: FilterInput, _name: string): FilterInput {\n return input;\n }\n\n /**\n * Default no-op implementation for addEdge.\n * Override if you need to track graph edges (e.g., visualization).\n */\n addEdge(_source: InputBase, _dest: InputBase): void {\n // No-op\n }\n\n /**\n * Default no-op implementation for addMetric.\n * Override if you need to collect metrics.\n */\n addMetric<K extends keyof MetricMap>(\n _metric: K,\n _value: number,\n ..._args: MetricMap[K]\n ): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to track server queries (e.g., ZeroContext, test delegates).\n */\n addServerQuery(_ast: AST, _ttl: TTL, _gotCallback?: GotCallback): () => void {\n return () => {};\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to track custom queries (e.g., ZeroContext, test delegates).\n */\n addCustomQuery(\n _ast: AST,\n _customQueryID: CustomQueryID,\n _ttl: TTL,\n _gotCallback?: GotCallback,\n ): () => void {\n return () => {};\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to handle query updates.\n */\n updateServerQuery(_ast: AST, _ttl: TTL): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to handle custom query updates.\n */\n updateCustomQuery(_customQueryID: CustomQueryID, _ttl: TTL): void {\n // No-op\n }\n\n /**\n * Default no-op implementation.\n * Override if you need to flush query changes.\n */\n flushQueryChanges(): void {\n // No-op\n }\n\n /**\n * Called when a transaction commits. Override to add custom behavior.\n * Default implementation returns a no-op cleanup function.\n */\n onTransactionCommit(_cb: CommitListener): () => void {\n return () => {};\n }\n\n /**\n * Validates run options. Override to add custom validation.\n * Default implementation is a no-op.\n */\n assertValidRunOptions(_options?: RunOptions): void {\n // No-op\n }\n\n abstract readonly defaultQueryComplete: boolean;\n\n /**\n * Default: pipelines can always be built immediately. Override (together\n * with `onPipelinesReady`) to defer pipeline construction.\n */\n get pipelinesReady(): boolean {\n return true;\n }\n\n onPipelinesReady(_cb: () => void): () => void {\n throw new Error(\n 'onPipelinesReady called on a delegate whose pipelines are always ready',\n );\n }\n\n // BuilderDelegate methods - must be implemented\n abstract getSource(name: string): Source | undefined;\n}\n\n// oxlint-disable-next-line require-await\nexport async function runImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n options?: RunOptions,\n): Promise<HumanReadable<TReturn>> {\n delegate.assertValidRunOptions(options);\n const v: TypedView<HumanReadable<TReturn>> = materializeImpl(\n query,\n delegate,\n undefined,\n {\n ttl: options?.ttl,\n },\n );\n if (options?.type === 'complete') {\n return new Promise(resolve => {\n v.addListener((data, type) => {\n if (type === 'complete') {\n v.destroy();\n resolve(data as HumanReadable<TReturn>);\n } else if (type === 'error') {\n v.destroy();\n resolve(Promise.reject(data));\n }\n });\n });\n }\n\n options?.type satisfies 'unknown' | undefined;\n\n const ret = v.data;\n v.destroy();\n return ret;\n}\n\nexport function preloadImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n options?: PreloadOptions,\n): {\n cleanup: () => void;\n complete: Promise<void>;\n} {\n const qi = asQueryInternals(query);\n const ttl = options?.ttl ?? DEFAULT_PRELOAD_TTL_MS;\n const {resolve, promise: complete} = resolver<void>();\n const {customQueryID, ast} = qi;\n if (customQueryID) {\n const cleanup = delegate.addCustomQuery(ast, customQueryID, ttl, got => {\n if (got) {\n resolve();\n }\n });\n return {\n cleanup,\n complete,\n };\n }\n\n const cleanup = delegate.addServerQuery(ast, ttl, got => {\n if (got) {\n resolve();\n }\n });\n return {\n cleanup,\n complete,\n };\n}\n\nexport function materializeImpl<\n TTable extends keyof TSchema['tables'] & string,\n TSchema extends Schema,\n TReturn,\n T,\n>(\n query: Query<TTable, TSchema, TReturn>,\n delegate: QueryDelegate,\n factory: ViewFactory<\n TTable,\n TSchema,\n TReturn,\n T\n // oxlint-disable-next-line no-explicit-any\n > = arrayViewFactory as any,\n options?: MaterializeOptions,\n): T {\n let ttl: TTL = options?.ttl ?? DEFAULT_TTL_MS;\n\n const qi = asQueryInternals(query);\n const {ast, format, customQueryID} = qi;\n const queryHash = qi.hash();\n\n const queryID = customQueryID\n ? hashOfNameAndArgs(customQueryID.name, customQueryID.args)\n : queryHash;\n const queryCompleteResolver = resolver<true>();\n // When the delegate cannot build pipelines yet, the view starts over an\n // empty DeferredInput and is hydrated later. A view must not report\n // `complete` until it has actually been hydrated, so completion is gated on\n // both the server's \"got\" and the pipeline being attached.\n const deferPipeline = !delegate.pipelinesReady;\n let attached = !deferPipeline;\n let gotQueries = delegate.defaultQueryComplete;\n let queryComplete: boolean | ErroredQuery = attached && gotQueries;\n const updateTTL = customQueryID\n ? (newTTL: TTL) => delegate.updateCustomQuery(customQueryID, newTTL)\n : (newTTL: TTL) => delegate.updateServerQuery(ast, newTTL);\n\n // Completion, and the end-to-end metric, require both the server's \"got\"\n // and the pipeline being attached: until then the view is still empty.\n const maybeResolveComplete = () => {\n if (attached && gotQueries && queryComplete !== true) {\n delegate.addMetric(\n 'query-materialization-end-to-end',\n performance.now() - t0,\n queryID,\n ast,\n );\n queryComplete = true;\n queryCompleteResolver.resolve(true);\n }\n };\n\n const gotCallback: GotCallback = (got, error) => {\n if (error) {\n queryCompleteResolver.reject(error);\n queryComplete = error;\n return;\n }\n\n if (got) {\n gotQueries = true;\n maybeResolveComplete();\n }\n };\n\n let removeCommitObserver: (() => void) | undefined;\n let removePendingAttach: (() => void) | undefined;\n const onDestroy = () => {\n removePendingAttach?.();\n removePendingAttach = undefined;\n input.destroy();\n removeCommitObserver?.();\n removeAddedQuery();\n };\n\n const t0 = performance.now();\n\n const removeAddedQuery = customQueryID\n ? delegate.addCustomQuery(ast, customQueryID, ttl, gotCallback)\n : delegate.addServerQuery(ast, ttl, gotCallback);\n\n const deferred = deferPipeline\n ? newDeferredInput(ast, delegate, queryID)\n : undefined;\n // No type annotation here: annotating this as `Input` widens it enough that\n // the view type loses the pipeline's concrete schema, and `Zero.run` then\n // stops rejecting a query built from a schema with legacy queries enabled\n // (custom.test.ts covers that rejection).\n const input = deferred ?? buildPipeline(ast, delegate, queryID);\n\n const view = delegate.batchViewUpdates(() =>\n (factory ?? arrayViewFactory)(\n query,\n input,\n format,\n onDestroy,\n cb => {\n removeCommitObserver = delegate.onTransactionCommit(cb);\n },\n queryComplete || queryCompleteResolver.promise,\n updateTTL,\n ),\n );\n\n if (!deferred) {\n delegate.addMetric(\n 'query-materialization-client',\n performance.now() - t0,\n queryID,\n );\n } else {\n // Registered after the factory ran so a throwing factory leaves nothing\n // behind.\n removePendingAttach = delegate.onPipelinesReady(() => {\n removePendingAttach = undefined;\n if (deferred.destroyed) {\n return;\n }\n const t1 = performance.now();\n try {\n deferred.attach();\n } catch (e) {\n // Surface the failure on this view and let the delegate decide how\n // to log it. Other pending pipelines are unaffected.\n const error: ErroredQuery = {\n error: 'app',\n id: queryID,\n name: customQueryID?.name ?? '',\n message: e instanceof Error ? e.message : String(e),\n };\n queryComplete = error;\n queryCompleteResolver.reject(error);\n throw e;\n }\n attached = true;\n delegate.addMetric(\n 'query-materialization-client',\n performance.now() - t1,\n queryID,\n );\n maybeResolveComplete();\n });\n }\n\n return view as T;\n}\n\n/**\n * Creates the placeholder input for a query whose pipeline cannot be built yet.\n *\n * `Input.getSchema()` is unconditional, so the placeholder needs the schema up\n * front. It is captured by building a pipeline and immediately destroying it:\n * building only connects to the sources, while the indexes and rows -- the\n * expensive part this deferral exists to postpone -- are read on the first\n * fetch. Measured at ~5us against ~500us for a single 100 row fetch.\n *\n * Building here also means a query that cannot be built at all (an unknown\n * table, `not(exists())` on the client) still throws from `materialize()`,\n * as it did before hydration was deferred.\n */\nfunction newDeferredInput(\n ast: AST,\n delegate: QueryDelegate,\n queryID: string,\n): DeferredInput {\n const build = () => buildPipeline(ast, delegate, queryID);\n const probe = build();\n try {\n return new DeferredInput(probe.getSchema(), build);\n } finally {\n probe.destroy();\n }\n}\n\nfunction arrayViewFactory<\n TTable extends string,\n TSchema extends Schema,\n TReturn,\n>(\n _query: QueryInternals<TTable, TSchema, TReturn>,\n input: Input,\n format: Format,\n onDestroy: () => void,\n onTransactionCommit: (cb: () => void) => void,\n queryComplete: true | ErroredQuery | Promise<true>,\n updateTTL: (ttl: TTL) => void,\n): TypedView<HumanReadable<TReturn>> {\n const v = new ArrayView<HumanReadable<TReturn>>(\n input,\n format,\n queryComplete,\n updateTTL,\n );\n v.onDestroy = onDestroy;\n onTransactionCommit(() => v.flush());\n return v;\n}\n"],"mappings":"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"}
|
|
@@ -44,6 +44,28 @@ export interface QueryDelegate extends BuilderDelegate, MetricsDelegate {
|
|
|
44
44
|
* data is always available.
|
|
45
45
|
*/
|
|
46
46
|
readonly defaultQueryComplete: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Whether query pipelines can be built against the sources right now.
|
|
49
|
+
*
|
|
50
|
+
* When `false`, `materialize` registers the query with the server as usual
|
|
51
|
+
* but returns a view over an empty placeholder input. The pipeline is built
|
|
52
|
+
* and the view hydrated when the delegate invokes the callbacks registered
|
|
53
|
+
* with {@link onPipelinesReady}. Zero uses this during cold boot so the
|
|
54
|
+
* replica is loaded into the IVM sources once, instead of being pushed row
|
|
55
|
+
* by row through every already-materialized pipeline.
|
|
56
|
+
*
|
|
57
|
+
*/
|
|
58
|
+
readonly pipelinesReady: boolean;
|
|
59
|
+
/**
|
|
60
|
+
* Register a callback to build a deferred pipeline once
|
|
61
|
+
* {@link pipelinesReady} becomes `true`. Callbacks are invoked in
|
|
62
|
+
* registration order inside `batchViewUpdates`, and the delegate notifies
|
|
63
|
+
* its commit listeners after the batch so views flush.
|
|
64
|
+
*
|
|
65
|
+
* Returns a function that unregisters the callback (used when the view is
|
|
66
|
+
* destroyed before the pipeline is built).
|
|
67
|
+
*/
|
|
68
|
+
onPipelinesReady(cb: () => void): () => void;
|
|
47
69
|
/** Using the default view factory creates a TypedView */
|
|
48
70
|
materialize<TTable extends keyof TSchema['tables'] & string, TSchema extends Schema, TReturn>(query: Query<TTable, TSchema, TReturn>, factory?: undefined, options?: MaterializeOptions): TypedView<HumanReadable<TReturn>>;
|
|
49
71
|
materialize<TTable extends keyof TSchema['tables'] & string, TSchema extends Schema, TReturn, T>(query: Query<TTable, TSchema, TReturn>, factory?: ViewFactory<TTable, TSchema, TReturn, T>, options?: MaterializeOptions): T;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-delegate.d.ts","sourceRoot":"","sources":["../../../../../zql/src/query/query-delegate.ts"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"query-delegate.d.ts","sourceRoot":"","sources":["../../../../../zql/src/query/query-delegate.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/query-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EACV,SAAS,EACT,QAAQ,EAGT,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACV,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAC,eAAe,EAAE,KAAK,EAAC,MAAM,+BAA+B,CAAC;AAG1E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,SAAS,EACT;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAC,CAC7B,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAC3B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,gBAAgB,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,YAiC1D;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,cAcrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACnC,QAAQ,CAyCV;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,CAmBxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,QAAQ,CAuBnE;
|
|
1
|
+
{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/query-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EACV,SAAS,EACT,QAAQ,EAGT,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACV,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAC,eAAe,EAAE,KAAK,EAAC,MAAM,+BAA+B,CAAC;AAG1E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,SAAS,EACT;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAC,CAC7B,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAC3B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,gBAAgB,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,YAiC1D;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,cAcrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACnC,QAAQ,CAyCV;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,CAmBxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,QAAQ,CAuBnE;AAgGD,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAWjE"}
|
|
@@ -72,6 +72,7 @@ function simpleConditionToSQL(filter) {
|
|
|
72
72
|
case "static": throw new Error("Static parameters must be replaced before conversion to SQL");
|
|
73
73
|
}
|
|
74
74
|
if (op === "LIKE" || op === "NOT LIKE" || op === "ILIKE" || op === "NOT ILIKE") return likeConditionToSQL(filter);
|
|
75
|
+
if ((op === "IS" || op === "IS NOT") && filter.right.type === "literal" && filter.right.value === null) return sql`${valuePositionToSQL(filter.left)} ${sql.__dangerous__rawValue(op)} NULL`;
|
|
75
76
|
return sql`${valuePositionToSQL(filter.left)} ${sql.__dangerous__rawValue(filter.op)} ${valuePositionToSQL(filter.right)}`;
|
|
76
77
|
}
|
|
77
78
|
function likeConditionToSQL(filter) {
|
|
@@ -105,7 +106,7 @@ function toSQLiteType(v, type) {
|
|
|
105
106
|
}
|
|
106
107
|
}
|
|
107
108
|
function nullableAwareEquality(field, value, columnType) {
|
|
108
|
-
if (value === null) return sql`${sql.ident(field)} IS
|
|
109
|
+
if (value === null) return sql`${sql.ident(field)} IS NULL`;
|
|
109
110
|
return columnType.optional === true ? sql`${sql.ident(field)} IS ${value}` : sql`${sql.ident(field)} = ${value}`;
|
|
110
111
|
}
|
|
111
112
|
function nullableAwareRangeComparison(field, value, operator, columnType) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-builder.js","names":[],"sources":["../../../../zqlite/src/query-builder.ts"],"sourcesContent":["import type {SQLQuery} from '@databases/sql';\nimport {assert} from '../../shared/src/asserts.ts';\nimport type {\n Condition,\n Ordering,\n SimpleCondition,\n ValuePosition,\n} from '../../zero-protocol/src/ast.ts';\nimport type {\n SchemaValue,\n ValueType,\n} from '../../zero-schema/src/table-schema.ts';\nimport type {Constraint} from '../../zql/src/ivm/constraint.ts';\nimport type {MultiConstraint, Start} from '../../zql/src/ivm/operator.ts';\nimport {sql} from './internal/sql.ts';\n\n/**\n * Condition type without correlated subqueries.\n * This matches the output of transformFilters from zql/builder/filter.ts\n */\nexport type NoSubqueryCondition = Exclude<\n Condition,\n {type: 'correlatedSubquery'}\n>;\n\nexport function buildSelectQuery(\n tableName: string,\n columns: Record<string, SchemaValue>,\n constraint: Constraint | undefined,\n filters: NoSubqueryCondition | undefined,\n order: Ordering | undefined,\n reverse: boolean | undefined,\n start: Start | undefined,\n multiConstraints?: readonly MultiConstraint[] | undefined,\n) {\n let query = sql`SELECT ${sql.join(\n Object.keys(columns).map(c => sql.ident(c)),\n sql`,`,\n )} FROM ${sql.ident(tableName)}`;\n const constraints: SQLQuery[] = constraintsToSQL(constraint, columns);\n\n if (multiConstraints) {\n for (const mc of multiConstraints) {\n if (mc.length > 0) {\n constraints.push(multiConstraintToSQL(mc, columns));\n }\n }\n }\n\n if (start) {\n assert(order !== undefined, 'start requires ordering');\n constraints.push(gatherStartConstraints(start, reverse, order, columns));\n }\n\n if (filters) {\n constraints.push(filtersToSQL(filters));\n }\n\n if (constraints.length > 0) {\n query = sql`${query} WHERE ${sql.join(constraints, sql` AND `)}`;\n }\n\n if (order && order.length > 0) {\n return sql`${query} ${orderByToSQL(order, !!reverse)}`;\n }\n return query;\n}\n\nexport function constraintsToSQL(\n constraint: Constraint | undefined,\n columns: Record<string, SchemaValue>,\n) {\n if (!constraint) {\n return [];\n }\n\n const constraints: SQLQuery[] = [];\n for (const [key, value] of Object.entries(constraint)) {\n constraints.push(\n sql`${sql.ident(key)} = ${toSQLiteType(value, columns[key].type)}`,\n );\n }\n\n return constraints;\n}\n\n/**\n * Builds a single batched IN clause from a `MultiConstraint`. All entries\n * are assumed to share the same shape (the keys of the first entry);\n * FlippedJoin derives them from the same parentKey for all children.\n *\n * Single-column form: `col IN (?, ?, ?)`\n * Compound form: `(a, b) IN (VALUES (?, ?), (?, ?), …)`\n *\n * NOTE: SQLite optimizes `col IN (literal-list)` using the column's index;\n * verified via EXPLAIN QUERY PLAN — see query-builder.test.ts.\n */\nexport function multiConstraintToSQL(\n multiConstraint: MultiConstraint,\n columns: Record<string, SchemaValue>,\n): SQLQuery {\n assert(multiConstraint.length > 0, 'multiConstraint must be non-empty');\n // All entries share the same keys; pull the column list from the first.\n const keys = Object.keys(multiConstraint[0]);\n assert(keys.length > 0, 'multiConstraint entries must have at least one key');\n // Subsequent entries must share the first entry's shape — the SQL form\n // is `(col_a, col_b, …) IN VALUES (…)`, with one binding per key per\n // entry. Heterogeneous keys would silently produce incorrect bindings.\n for (let i = 1; i < multiConstraint.length; i++) {\n const entry = multiConstraint[i];\n assert(\n Object.keys(entry).length === keys.length && keys.every(k => k in entry),\n () =>\n `multiConstraint entries must share the same keys (entry 0: [${keys.join(\n ',',\n )}], entry ${i}: [${Object.keys(entry).join(',')}])`,\n );\n }\n\n if (keys.length === 1) {\n const key = keys[0];\n const colType = columns[key].type;\n return sql`${sql.ident(key)} IN (${sql.join(\n multiConstraint.map(c => sql`${toSQLiteType(c[key], colType)}`),\n sql`,`,\n )})`;\n }\n\n // Compound: `(col_a, col_b, …) IN (VALUES (?, ?, …), …)`\n const colList = sql`(${sql.join(\n keys.map(k => sql.ident(k)),\n sql`,`,\n )})`;\n const rows = multiConstraint.map(\n c =>\n sql`(${sql.join(\n keys.map(k => sql`${toSQLiteType(c[k], columns[k].type)}`),\n sql`,`,\n )})`,\n );\n return sql`${colList} IN (VALUES ${sql.join(rows, sql`,`)})`;\n}\n\nexport function orderByToSQL(order: Ordering, reverse: boolean): SQLQuery {\n if (reverse) {\n return sql`ORDER BY ${sql.join(\n order.map(\n s =>\n sql`${sql.ident(s[0])} ${sql.__dangerous__rawValue(\n s[1] === 'asc' ? 'desc' : 'asc',\n )}`,\n ),\n sql`, `,\n )}`;\n } else {\n return sql`ORDER BY ${sql.join(\n order.map(\n s => sql`${sql.ident(s[0])} ${sql.__dangerous__rawValue(s[1])}`,\n ),\n sql`, `,\n )}`;\n }\n}\n\n/**\n * Converts filters (conditions) to SQL WHERE clause.\n * This applies all filters present in the AST for a query to the source.\n */\nexport function filtersToSQL(filters: NoSubqueryCondition): SQLQuery {\n switch (filters.type) {\n case 'simple':\n return simpleConditionToSQL(filters);\n case 'and':\n return filters.conditions.length > 0\n ? sql`(${sql.join(\n filters.conditions.map(condition =>\n filtersToSQL(condition as NoSubqueryCondition),\n ),\n sql` AND `,\n )})`\n : sql`TRUE`;\n case 'or':\n return filters.conditions.length > 0\n ? sql`(${sql.join(\n filters.conditions.map(condition =>\n filtersToSQL(condition as NoSubqueryCondition),\n ),\n sql` OR `,\n )})`\n : sql`FALSE`;\n }\n}\n\nfunction simpleConditionToSQL(filter: SimpleCondition): SQLQuery {\n const {op} = filter;\n if (op === 'IN' || op === 'NOT IN') {\n switch (filter.right.type) {\n case 'literal':\n return sql`${valuePositionToSQL(\n filter.left,\n )} ${sql.__dangerous__rawValue(\n filter.op,\n )} (SELECT value FROM json_each(${JSON.stringify(\n filter.right.value,\n )}))`;\n case 'static':\n throw new Error(\n 'Static parameters must be replaced before conversion to SQL',\n );\n }\n }\n if (\n op === 'LIKE' ||\n op === 'NOT LIKE' ||\n op === 'ILIKE' ||\n op === 'NOT ILIKE'\n ) {\n return likeConditionToSQL(filter);\n }\n\n return sql`${valuePositionToSQL(filter.left)} ${sql.__dangerous__rawValue(\n filter.op,\n )} ${valuePositionToSQL(filter.right)}`;\n}\n\nfunction likeConditionToSQL(filter: SimpleCondition): SQLQuery {\n const {op} = filter;\n // Mirror Postgres pattern-matching semantics:\n // * LIKE is case-sensitive. The replica connection runs with\n // `PRAGMA case_sensitive_like = ON` (see db.ts), so the bare LIKE\n // operator is case-sensitive.\n // * ILIKE is case-insensitive. We lower() both operands using the\n // Unicode-aware lower() that @rocicorp/zero-sqlite3 provides via ICU,\n // mirroring the toLowerCase() used by the in-memory IVM matcher\n // (see zql/src/builder/like.ts).\n // * Backslash is the default escape character in Postgres and in the IVM\n // matcher, but SQLite has no default, so we specify `ESCAPE '\\'`\n // explicitly. The SQL literal '\\' is a single backslash (SQLite does not\n // process backslash escapes inside string literals).\n const caseInsensitive = op === 'ILIKE' || op === 'NOT ILIKE';\n const negated = op === 'NOT LIKE' || op === 'NOT ILIKE';\n const likeOp = sql.__dangerous__rawValue(negated ? 'NOT LIKE' : 'LIKE');\n\n const left = valuePositionToSQL(filter.left);\n const right = valuePositionToSQL(filter.right);\n if (caseInsensitive) {\n return sql`lower(${left}) ${likeOp} lower(${right}) ESCAPE '\\\\'`;\n }\n return sql`${left} ${likeOp} ${right} ESCAPE '\\\\'`;\n}\n\nfunction valuePositionToSQL(value: ValuePosition): SQLQuery {\n switch (value.type) {\n case 'column':\n return sql.ident(value.name);\n case 'literal':\n return sql`${toSQLiteType(value.value, getJsType(value.value))}`;\n case 'static':\n throw new Error(\n 'Static parameters must be replaced before conversion to SQL',\n );\n }\n}\n\nfunction getJsType(value: unknown): ValueType {\n if (value === null) {\n return 'null';\n }\n return typeof value === 'string'\n ? 'string'\n : typeof value === 'number'\n ? 'number'\n : typeof value === 'boolean'\n ? 'boolean'\n : 'json';\n}\n\nexport function toSQLiteType(v: unknown, type: ValueType): unknown {\n switch (type) {\n case 'boolean':\n return v === null ? null : v ? 1 : 0;\n case 'number':\n case 'string':\n case 'null':\n return v;\n case 'json':\n return JSON.stringify(v);\n }\n}\n\nfunction nullableAwareEquality(\n field: string,\n value: unknown,\n columnType: SchemaValue,\n): SQLQuery {\n if (value === null) {\n // A NULL bound value proves the column is nullable regardless of the\n // column metadata, and `=` never matches NULL — `IS` selects the NULL\n // tie-break group a cursor anchored on a NULL value needs.\n return sql`${sql.ident(field)} IS ${value}`;\n }\n // Use = instead of IS for non-nullable columns to enable better\n // index usage in SQLite.\n return columnType.optional === true\n ? sql`${sql.ident(field)} IS ${value}`\n : sql`${sql.ident(field)} = ${value}`;\n}\n\nfunction nullableAwareRangeComparison(\n field: string,\n value: unknown,\n operator: '>' | '<',\n columnType: SchemaValue,\n): SQLQuery {\n if (value === null) {\n return operator === '>' ? sql`${sql.ident(field)} IS NOT NULL` : sql`FALSE`;\n }\n\n // For non-nullable columns, skip IS NULL checks to avoid breaking\n // SQLite's MULTI-INDEX OR optimization, which falls back to a full\n // table scan when any OR branch involves NULL.\n // See: https://github.com/rocicorp/mono/pull/5542\n const comparison = sql`${sql.ident(field)} ${sql.__dangerous__rawValue(\n operator,\n )} ${value}`;\n if (columnType.optional !== true) {\n return comparison;\n }\n\n // The bound is non-NULL here. NULLs sort before every non-NULL value, so\n // `>` already excludes them and needs no guard, while `<` must admit the\n // NULL group explicitly — a bare `col < ?` would silently drop NULL rows\n // from a backward walk.\n return operator === '>'\n ? comparison\n : sql`(${sql.ident(field)} IS NULL OR ${comparison})`;\n}\n\nfunction sargableLeadingStartBound(\n field: string,\n value: unknown,\n operator: '>' | '<',\n columnType: SchemaValue,\n): SQLQuery | undefined {\n // A NULL bound value proves the column is nullable regardless of the\n // column metadata, and a bare range bound is not sound there: `col >= NULL`\n // is never true, so instead of being redundant it would annihilate the\n // whole start constraint. A nullable column also cannot use a `<` bound,\n // because the start constraint must retain the NULL group. For `>`, NULLs\n // sort before the non-NULL bound, so `col >= value` remains sound.\n if (value === null || (columnType.optional === true && operator === '<')) {\n return undefined;\n }\n\n const inclusiveOperator = operator === '>' ? '>=' : '<=';\n return sql`${sql.ident(field)} ${sql.__dangerous__rawValue(\n inclusiveOperator,\n )} ${value}`;\n}\n\n/**\n * The ordering could be complex such as:\n * `ORDER BY a ASC, b DESC, c ASC`\n *\n * In those cases, we need to encode the constraints as various\n * `OR` clauses.\n *\n * E.g.,\n *\n * to get the row after (a = 1, b = 2, c = 3) would be:\n *\n * `WHERE a > 1 OR (a = 1 AND b < 2) OR (a = 1 AND b = 2 AND c > 3)`\n *\n * - after vs before flips the comparison operators.\n * - inclusive adds a final `OR` clause for the exact match.\n */\nfunction gatherStartConstraints(\n start: Start,\n reverse: boolean | undefined,\n order: Ordering,\n columnTypes: Record<string, SchemaValue>,\n): SQLQuery {\n const constraints: SQLQuery[] = [];\n const {row: from, basis} = start;\n let leadingBound: SQLQuery | undefined;\n\n for (let i = 0; i < order.length; i++) {\n const group: SQLQuery[] = [];\n const [iField, iDirection] = order[i];\n for (let j = 0; j <= i; j++) {\n if (j === i) {\n const columnType = columnTypes[iField];\n const constraintValue = toSQLiteType(\n from[iField] ?? null,\n columnType.type,\n );\n const operator =\n iDirection === 'asc' ? (reverse ? '<' : '>') : reverse ? '>' : '<';\n if (i === 0) {\n leadingBound = sargableLeadingStartBound(\n iField,\n constraintValue,\n operator,\n columnType,\n );\n }\n group.push(\n nullableAwareRangeComparison(\n iField,\n constraintValue,\n operator,\n columnType,\n ),\n );\n } else {\n const [jField] = order[j];\n const columnType = columnTypes[jField];\n const value = toSQLiteType(from[jField] ?? null, columnType.type);\n group.push(nullableAwareEquality(jField, value, columnType));\n }\n }\n constraints.push(sql`(${sql.join(group, sql` AND `)})`);\n }\n\n if (basis === 'at') {\n constraints.push(\n sql`(${sql.join(\n order.map(([field]) => {\n const columnType = columnTypes[field];\n const value = toSQLiteType(from[field] ?? null, columnType.type);\n return nullableAwareEquality(field, value, columnType);\n }),\n sql` AND `,\n )})`,\n );\n }\n\n const lexicographicStart = sql`(${sql.join(constraints, sql` OR `)})`;\n return leadingBound === undefined\n ? lexicographicStart\n : sql`(${leadingBound} AND ${lexicographicStart})`;\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"query-builder.js","names":[],"sources":["../../../../zqlite/src/query-builder.ts"],"sourcesContent":["import type {SQLQuery} from '@databases/sql';\nimport {assert} from '../../shared/src/asserts.ts';\nimport type {\n Condition,\n Ordering,\n SimpleCondition,\n ValuePosition,\n} from '../../zero-protocol/src/ast.ts';\nimport type {\n SchemaValue,\n ValueType,\n} from '../../zero-schema/src/table-schema.ts';\nimport type {Constraint} from '../../zql/src/ivm/constraint.ts';\nimport type {MultiConstraint, Start} from '../../zql/src/ivm/operator.ts';\nimport {sql} from './internal/sql.ts';\n\n/**\n * Condition type without correlated subqueries.\n * This matches the output of transformFilters from zql/builder/filter.ts\n */\nexport type NoSubqueryCondition = Exclude<\n Condition,\n {type: 'correlatedSubquery'}\n>;\n\nexport function buildSelectQuery(\n tableName: string,\n columns: Record<string, SchemaValue>,\n constraint: Constraint | undefined,\n filters: NoSubqueryCondition | undefined,\n order: Ordering | undefined,\n reverse: boolean | undefined,\n start: Start | undefined,\n multiConstraints?: readonly MultiConstraint[] | undefined,\n) {\n let query = sql`SELECT ${sql.join(\n Object.keys(columns).map(c => sql.ident(c)),\n sql`,`,\n )} FROM ${sql.ident(tableName)}`;\n const constraints: SQLQuery[] = constraintsToSQL(constraint, columns);\n\n if (multiConstraints) {\n for (const mc of multiConstraints) {\n if (mc.length > 0) {\n constraints.push(multiConstraintToSQL(mc, columns));\n }\n }\n }\n\n if (start) {\n assert(order !== undefined, 'start requires ordering');\n constraints.push(gatherStartConstraints(start, reverse, order, columns));\n }\n\n if (filters) {\n constraints.push(filtersToSQL(filters));\n }\n\n if (constraints.length > 0) {\n query = sql`${query} WHERE ${sql.join(constraints, sql` AND `)}`;\n }\n\n if (order && order.length > 0) {\n return sql`${query} ${orderByToSQL(order, !!reverse)}`;\n }\n return query;\n}\n\nexport function constraintsToSQL(\n constraint: Constraint | undefined,\n columns: Record<string, SchemaValue>,\n) {\n if (!constraint) {\n return [];\n }\n\n const constraints: SQLQuery[] = [];\n for (const [key, value] of Object.entries(constraint)) {\n constraints.push(\n sql`${sql.ident(key)} = ${toSQLiteType(value, columns[key].type)}`,\n );\n }\n\n return constraints;\n}\n\n/**\n * Builds a single batched IN clause from a `MultiConstraint`. All entries\n * are assumed to share the same shape (the keys of the first entry);\n * FlippedJoin derives them from the same parentKey for all children.\n *\n * Single-column form: `col IN (?, ?, ?)`\n * Compound form: `(a, b) IN (VALUES (?, ?), (?, ?), …)`\n *\n * NOTE: SQLite optimizes `col IN (literal-list)` using the column's index;\n * verified via EXPLAIN QUERY PLAN — see query-builder.test.ts.\n */\nexport function multiConstraintToSQL(\n multiConstraint: MultiConstraint,\n columns: Record<string, SchemaValue>,\n): SQLQuery {\n assert(multiConstraint.length > 0, 'multiConstraint must be non-empty');\n // All entries share the same keys; pull the column list from the first.\n const keys = Object.keys(multiConstraint[0]);\n assert(keys.length > 0, 'multiConstraint entries must have at least one key');\n // Subsequent entries must share the first entry's shape — the SQL form\n // is `(col_a, col_b, …) IN VALUES (…)`, with one binding per key per\n // entry. Heterogeneous keys would silently produce incorrect bindings.\n for (let i = 1; i < multiConstraint.length; i++) {\n const entry = multiConstraint[i];\n assert(\n Object.keys(entry).length === keys.length && keys.every(k => k in entry),\n () =>\n `multiConstraint entries must share the same keys (entry 0: [${keys.join(\n ',',\n )}], entry ${i}: [${Object.keys(entry).join(',')}])`,\n );\n }\n\n if (keys.length === 1) {\n const key = keys[0];\n const colType = columns[key].type;\n return sql`${sql.ident(key)} IN (${sql.join(\n multiConstraint.map(c => sql`${toSQLiteType(c[key], colType)}`),\n sql`,`,\n )})`;\n }\n\n // Compound: `(col_a, col_b, …) IN (VALUES (?, ?, …), …)`\n const colList = sql`(${sql.join(\n keys.map(k => sql.ident(k)),\n sql`,`,\n )})`;\n const rows = multiConstraint.map(\n c =>\n sql`(${sql.join(\n keys.map(k => sql`${toSQLiteType(c[k], columns[k].type)}`),\n sql`,`,\n )})`,\n );\n return sql`${colList} IN (VALUES ${sql.join(rows, sql`,`)})`;\n}\n\nexport function orderByToSQL(order: Ordering, reverse: boolean): SQLQuery {\n if (reverse) {\n return sql`ORDER BY ${sql.join(\n order.map(\n s =>\n sql`${sql.ident(s[0])} ${sql.__dangerous__rawValue(\n s[1] === 'asc' ? 'desc' : 'asc',\n )}`,\n ),\n sql`, `,\n )}`;\n } else {\n return sql`ORDER BY ${sql.join(\n order.map(\n s => sql`${sql.ident(s[0])} ${sql.__dangerous__rawValue(s[1])}`,\n ),\n sql`, `,\n )}`;\n }\n}\n\n/**\n * Converts filters (conditions) to SQL WHERE clause.\n * This applies all filters present in the AST for a query to the source.\n */\nexport function filtersToSQL(filters: NoSubqueryCondition): SQLQuery {\n switch (filters.type) {\n case 'simple':\n return simpleConditionToSQL(filters);\n case 'and':\n return filters.conditions.length > 0\n ? sql`(${sql.join(\n filters.conditions.map(condition =>\n filtersToSQL(condition as NoSubqueryCondition),\n ),\n sql` AND `,\n )})`\n : sql`TRUE`;\n case 'or':\n return filters.conditions.length > 0\n ? sql`(${sql.join(\n filters.conditions.map(condition =>\n filtersToSQL(condition as NoSubqueryCondition),\n ),\n sql` OR `,\n )})`\n : sql`FALSE`;\n }\n}\n\nfunction simpleConditionToSQL(filter: SimpleCondition): SQLQuery {\n const {op} = filter;\n if (op === 'IN' || op === 'NOT IN') {\n switch (filter.right.type) {\n case 'literal':\n return sql`${valuePositionToSQL(\n filter.left,\n )} ${sql.__dangerous__rawValue(\n filter.op,\n )} (SELECT value FROM json_each(${JSON.stringify(\n filter.right.value,\n )}))`;\n case 'static':\n throw new Error(\n 'Static parameters must be replaced before conversion to SQL',\n );\n }\n }\n if (\n op === 'LIKE' ||\n op === 'NOT LIKE' ||\n op === 'ILIKE' ||\n op === 'NOT ILIKE'\n ) {\n return likeConditionToSQL(filter);\n }\n\n if (\n (op === 'IS' || op === 'IS NOT') &&\n filter.right.type === 'literal' &&\n filter.right.value === null\n ) {\n return sql`${valuePositionToSQL(filter.left)} ${sql.__dangerous__rawValue(\n op,\n )} NULL`;\n }\n\n return sql`${valuePositionToSQL(filter.left)} ${sql.__dangerous__rawValue(\n filter.op,\n )} ${valuePositionToSQL(filter.right)}`;\n}\n\nfunction likeConditionToSQL(filter: SimpleCondition): SQLQuery {\n const {op} = filter;\n // Mirror Postgres pattern-matching semantics:\n // * LIKE is case-sensitive. The replica connection runs with\n // `PRAGMA case_sensitive_like = ON` (see db.ts), so the bare LIKE\n // operator is case-sensitive.\n // * ILIKE is case-insensitive. We lower() both operands using the\n // Unicode-aware lower() that @rocicorp/zero-sqlite3 provides via ICU,\n // mirroring the toLowerCase() used by the in-memory IVM matcher\n // (see zql/src/builder/like.ts).\n // * Backslash is the default escape character in Postgres and in the IVM\n // matcher, but SQLite has no default, so we specify `ESCAPE '\\'`\n // explicitly. The SQL literal '\\' is a single backslash (SQLite does not\n // process backslash escapes inside string literals).\n const caseInsensitive = op === 'ILIKE' || op === 'NOT ILIKE';\n const negated = op === 'NOT LIKE' || op === 'NOT ILIKE';\n const likeOp = sql.__dangerous__rawValue(negated ? 'NOT LIKE' : 'LIKE');\n\n const left = valuePositionToSQL(filter.left);\n const right = valuePositionToSQL(filter.right);\n if (caseInsensitive) {\n return sql`lower(${left}) ${likeOp} lower(${right}) ESCAPE '\\\\'`;\n }\n return sql`${left} ${likeOp} ${right} ESCAPE '\\\\'`;\n}\n\nfunction valuePositionToSQL(value: ValuePosition): SQLQuery {\n switch (value.type) {\n case 'column':\n return sql.ident(value.name);\n case 'literal':\n return sql`${toSQLiteType(value.value, getJsType(value.value))}`;\n case 'static':\n throw new Error(\n 'Static parameters must be replaced before conversion to SQL',\n );\n }\n}\n\nfunction getJsType(value: unknown): ValueType {\n if (value === null) {\n return 'null';\n }\n return typeof value === 'string'\n ? 'string'\n : typeof value === 'number'\n ? 'number'\n : typeof value === 'boolean'\n ? 'boolean'\n : 'json';\n}\n\nexport function toSQLiteType(v: unknown, type: ValueType): unknown {\n switch (type) {\n case 'boolean':\n return v === null ? null : v ? 1 : 0;\n case 'number':\n case 'string':\n case 'null':\n return v;\n case 'json':\n return JSON.stringify(v);\n }\n}\n\nfunction nullableAwareEquality(\n field: string,\n value: unknown,\n columnType: SchemaValue,\n): SQLQuery {\n if (value === null) {\n // A NULL bound value proves the column is nullable regardless of the\n // column metadata, and `=` never matches NULL — `IS` selects the NULL\n // tie-break group a cursor anchored on a NULL value needs.\n return sql`${sql.ident(field)} IS NULL`;\n }\n // Use = instead of IS for non-nullable columns to enable better\n // index usage in SQLite.\n return columnType.optional === true\n ? sql`${sql.ident(field)} IS ${value}`\n : sql`${sql.ident(field)} = ${value}`;\n}\n\nfunction nullableAwareRangeComparison(\n field: string,\n value: unknown,\n operator: '>' | '<',\n columnType: SchemaValue,\n): SQLQuery {\n if (value === null) {\n return operator === '>' ? sql`${sql.ident(field)} IS NOT NULL` : sql`FALSE`;\n }\n\n // For non-nullable columns, skip IS NULL checks to avoid breaking\n // SQLite's MULTI-INDEX OR optimization, which falls back to a full\n // table scan when any OR branch involves NULL.\n // See: https://github.com/rocicorp/mono/pull/5542\n const comparison = sql`${sql.ident(field)} ${sql.__dangerous__rawValue(\n operator,\n )} ${value}`;\n if (columnType.optional !== true) {\n return comparison;\n }\n\n // The bound is non-NULL here. NULLs sort before every non-NULL value, so\n // `>` already excludes them and needs no guard, while `<` must admit the\n // NULL group explicitly — a bare `col < ?` would silently drop NULL rows\n // from a backward walk.\n return operator === '>'\n ? comparison\n : sql`(${sql.ident(field)} IS NULL OR ${comparison})`;\n}\n\nfunction sargableLeadingStartBound(\n field: string,\n value: unknown,\n operator: '>' | '<',\n columnType: SchemaValue,\n): SQLQuery | undefined {\n // A NULL bound value proves the column is nullable regardless of the\n // column metadata, and a bare range bound is not sound there: `col >= NULL`\n // is never true, so instead of being redundant it would annihilate the\n // whole start constraint. A nullable column also cannot use a `<` bound,\n // because the start constraint must retain the NULL group. For `>`, NULLs\n // sort before the non-NULL bound, so `col >= value` remains sound.\n if (value === null || (columnType.optional === true && operator === '<')) {\n return undefined;\n }\n\n const inclusiveOperator = operator === '>' ? '>=' : '<=';\n return sql`${sql.ident(field)} ${sql.__dangerous__rawValue(\n inclusiveOperator,\n )} ${value}`;\n}\n\n/**\n * The ordering could be complex such as:\n * `ORDER BY a ASC, b DESC, c ASC`\n *\n * In those cases, we need to encode the constraints as various\n * `OR` clauses.\n *\n * E.g.,\n *\n * to get the row after (a = 1, b = 2, c = 3) would be:\n *\n * `WHERE a > 1 OR (a = 1 AND b < 2) OR (a = 1 AND b = 2 AND c > 3)`\n *\n * - after vs before flips the comparison operators.\n * - inclusive adds a final `OR` clause for the exact match.\n */\nfunction gatherStartConstraints(\n start: Start,\n reverse: boolean | undefined,\n order: Ordering,\n columnTypes: Record<string, SchemaValue>,\n): SQLQuery {\n const constraints: SQLQuery[] = [];\n const {row: from, basis} = start;\n let leadingBound: SQLQuery | undefined;\n\n for (let i = 0; i < order.length; i++) {\n const group: SQLQuery[] = [];\n const [iField, iDirection] = order[i];\n for (let j = 0; j <= i; j++) {\n if (j === i) {\n const columnType = columnTypes[iField];\n const constraintValue = toSQLiteType(\n from[iField] ?? null,\n columnType.type,\n );\n const operator =\n iDirection === 'asc' ? (reverse ? '<' : '>') : reverse ? '>' : '<';\n if (i === 0) {\n leadingBound = sargableLeadingStartBound(\n iField,\n constraintValue,\n operator,\n columnType,\n );\n }\n group.push(\n nullableAwareRangeComparison(\n iField,\n constraintValue,\n operator,\n columnType,\n ),\n );\n } else {\n const [jField] = order[j];\n const columnType = columnTypes[jField];\n const value = toSQLiteType(from[jField] ?? null, columnType.type);\n group.push(nullableAwareEquality(jField, value, columnType));\n }\n }\n constraints.push(sql`(${sql.join(group, sql` AND `)})`);\n }\n\n if (basis === 'at') {\n constraints.push(\n sql`(${sql.join(\n order.map(([field]) => {\n const columnType = columnTypes[field];\n const value = toSQLiteType(from[field] ?? null, columnType.type);\n return nullableAwareEquality(field, value, columnType);\n }),\n sql` AND `,\n )})`,\n );\n }\n\n const lexicographicStart = sql`(${sql.join(constraints, sql` OR `)})`;\n return leadingBound === undefined\n ? lexicographicStart\n : sql`(${leadingBound} AND ${lexicographicStart})`;\n}\n"],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sqlite-stat-fanout.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;;IAkB3B;;;;;;;;OAQG;gBACS,EAAE,EAAE,QAAQ,EAAE,aAAa,SAAI;
|
|
1
|
+
{"version":3,"file":"sqlite-stat-fanout.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;;IAkB3B;;;;;;;;OAQG;gBACS,EAAE,EAAE,QAAQ,EAAE,aAAa,SAAI;IA2B3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY;IAkC7D;;;OAGG;IACH,UAAU,IAAI,IAAI;CAkQnB"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sqlite-stat-fanout.js","names":["#db","#defaultFanout","#cache","#stat4Stmt","#stat1Stmt","#indexStmt","#getFanoutFromStat4","#getFanoutFromStat1","#findIndexForColumns","#decodeSampleIsNull","#isPrefixMatch"],"sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"sourcesContent":["import type {Database} from './db.ts';\n\n/**\n * Result of fanout calculation from SQLite statistics.\n */\nexport interface FanoutResult {\n /**\n * The fanout value (average rows per distinct value of the join column).\n * For non-NULL joins, this represents how many child rows exist per parent key.\n */\n fanout: number;\n confidence: 'high' | 'med' | 'none';\n\n /**\n * Source of the fanout calculation.\n * - 'stat4': From sqlite_stat4 histogram (most accurate, excludes NULLs)\n * - 'stat1': From sqlite_stat1 average (includes NULLs, may overestimate)\n * - 'default': Fallback constant when statistics unavailable\n */\n source: 'stat4' | 'stat1' | 'default';\n}\n\n/**\n * Sample from sqlite_stat4 histogram.\n */\ninterface Stat4Sample {\n /** \"N1 N2\" = rows equal to sample (N1=first col, N2=if composite) */\n neq: string;\n /** \"N1 N2\" = rows less than sample */\n nlt: string;\n /** \"N1 N2\" = distinct values less than sample */\n ndlt: string;\n /** The actual sample value (binary encoded) */\n sample: Buffer;\n}\n\n/**\n * Computes join fanout factors from SQLite statistics tables.\n *\n * Fanout is the average number of child rows per distinct parent key value,\n * used to estimate join cardinality in query planning.\n *\n * ## Problem\n *\n * sqlite_stat1 includes NULL rows in its calculation, which can significantly\n * overestimate fanout for sparse foreign keys:\n *\n * ```\n * Example: 100 tasks, 20 with project_id, 80 with NULL\n * - stat1 reports: \"100 17\" → fanout = 17 (WRONG - includes NULLs)\n * - stat4 shows: NULL samples with fanout=80, non-NULL samples with fanout=4\n * - True fanout: 4 (CORRECT)\n * ```\n *\n * ## Solution\n *\n * This class uses sqlite_stat4 histogram to separate NULL and non-NULL samples,\n * providing accurate fanout for non-NULL joins.\n *\n * ## Usage\n *\n * ```typescript\n * const calculator = new SQLiteStatFanout(db);\n *\n * // Get fanout for posts.userId → users.id join\n * const result = calculator.getFanout('posts', 'userId');\n *\n * if (result.source === 'stat4') {\n * // Accurate: excludes NULLs, samples actual distribution\n * console.log(`Fanout: ${result.fanout} (from stat4)`);\n * } else if (result.source === 'stat1') {\n * // Conservative: includes NULLs, may overestimate\n * console.log(`Fanout: ${result.fanout} (from stat1, includes NULLs)`);\n * } else {\n * // Fallback: no statistics available\n * console.log(`Fanout: ${result.fanout} (default estimate)`);\n * }\n * ```\n *\n * ## Requirements\n *\n * - SQLite compiled with ENABLE_STAT4 (most builds include this)\n * - `ANALYZE` command run on the database\n * - Index exists on the join column\n *\n * @see https://sqlite.org/fileformat2.html#stat4tab\n * @see packages/zql/src/planner/SELECTIVITY_PLAN.md\n */\nexport class SQLiteStatFanout {\n readonly #db: Database;\n readonly #defaultFanout: number;\n\n /**\n * Cache of fanout results by table and columns.\n * Key format: \"tableName:col1,col2,col3\" (sorted alphabetically)\n */\n readonly #cache = new Map<string, FanoutResult>();\n\n /**\n * Prepared statements for querying SQLite statistics tables.\n * Prepared once in constructor for performance.\n */\n readonly #stat4Stmt: ReturnType<Database['prepare']>;\n readonly #stat1Stmt: ReturnType<Database['prepare']>;\n readonly #indexStmt: ReturnType<Database['prepare']>;\n\n /**\n * Creates a new fanout calculator.\n *\n * @param db Database instance\n * @param defaultFanout Default fanout when statistics unavailable (default: 3)\n * - 1: Conservative (assumes FK relationships)\n * - 3: Moderate (recommended, safe middle ground)\n * - 10: SQLite's default (optimistic)\n */\n constructor(db: Database, defaultFanout = 3) {\n this.#db = db;\n this.#defaultFanout = defaultFanout;\n\n // Prepare SQL statements once for reuse across multiple getFanout() calls\n this.#stat4Stmt = this.#db.prepare(`\n SELECT neq, nlt, ndlt, sample\n FROM sqlite_stat4\n WHERE tbl = ? AND idx = ?\n ORDER BY nlt\n `);\n\n this.#stat1Stmt = this.#db.prepare(`\n SELECT stat\n FROM sqlite_stat1\n WHERE tbl = ? AND idx = ?\n `);\n\n this.#indexStmt = this.#db.prepare(`\n SELECT il.name as index_name, ii.seqno, ii.name as column_name\n FROM pragma_index_list(?) il\n JOIN pragma_index_info(il.name) ii\n ORDER BY il.seq, ii.seqno\n `);\n }\n\n /**\n * Gets the fanout factor for join column(s).\n *\n * Fanout = average number of child rows per distinct parent key value(s).\n *\n * ## Strategy\n *\n * 1. Try sqlite_stat4 (best): Histogram with separate NULL/non-NULL samples\n * 2. Fallback to sqlite_stat1: Average across all rows (includes NULLs)\n * 3. Fallback to default: When no statistics available\n *\n * ## Compound Indexes\n *\n * For multi-column joins, finds indexes where ALL columns appear as an\n * exact prefix. Uses the appropriate depth in stat1/stat4.\n *\n * Example:\n * - Columns: `['customerId', 'storeId']`\n * - Matches index: `(customerId, storeId, date)` at depth 2\n * - Uses stat1 parts[2] or stat4 neq[1] for accurate fanout\n *\n * ## Caching\n *\n * Results are cached per (table, columns) combination. Clear the cache if\n * you run ANALYZE to update statistics.\n *\n * @param tableName Table containing the join column(s)\n * @param columns Array of column names (one or more columns)\n * @returns Fanout result with value and source\n */\n getFanout(tableName: string, columns: string[]): FanoutResult {\n // Cache key uses sorted columns for consistency\n const cacheKey = `${tableName}:${columns.toSorted().join(',')}`;\n const cached = this.#cache.get(cacheKey);\n if (cached) {\n return cached;\n }\n\n // Strategy 1: Try stat4 first (most accurate)\n // NOTE: columns are NOT sorted - preserves Object.keys() order from constraint\n // Matching is order-independent (flexible), but we keep original order for consistency\n const stat4Result = this.#getFanoutFromStat4(tableName, columns);\n if (stat4Result) {\n this.#cache.set(cacheKey, stat4Result);\n return stat4Result;\n }\n\n // Strategy 2: Fallback to stat1 (includes NULLs)\n const stat1Result = this.#getFanoutFromStat1(tableName, columns);\n if (stat1Result) {\n this.#cache.set(cacheKey, stat1Result);\n return stat1Result;\n }\n\n // Strategy 3: Use default\n const defaultResult: FanoutResult = {\n fanout: this.#defaultFanout,\n confidence: 'none',\n source: 'default',\n };\n this.#cache.set(cacheKey, defaultResult);\n return defaultResult;\n }\n\n /**\n * Clears the fanout cache.\n * Call this after running ANALYZE to pick up updated statistics.\n */\n clearCache(): void {\n this.#cache.clear();\n }\n\n /**\n * Gets fanout from sqlite_stat4 histogram.\n *\n * Queries stat4 samples, decodes to identify NULLs, and returns\n * the median fanout of non-NULL samples.\n *\n * For compound indexes, uses the neq value at the appropriate depth.\n *\n * @param columns Array of column names to get fanout for\n * @returns Fanout result or undefined if stat4 unavailable\n */\n #getFanoutFromStat4(\n tableName: string,\n columns: string[],\n ): FanoutResult | undefined {\n try {\n // Find index containing the columns as a prefix\n const indexInfo = this.#findIndexForColumns(tableName, columns);\n if (!indexInfo) {\n return undefined;\n }\n\n // Query stat4 samples for this index (using prepared statement)\n const samples = this.#stat4Stmt.all(\n tableName,\n indexInfo.indexName,\n ) as Stat4Sample[];\n\n if (samples.length === 0) {\n return undefined;\n }\n\n // Decode samples and separate NULL from non-NULL\n // Use depth-1 for neq array index (depth is 1-based, array is 0-based)\n const neqIndex = indexInfo.depth - 1;\n const decodedSamples = samples.map(s => {\n const neqParts = s.neq.split(' ');\n return {\n fanout: parseInt(neqParts[neqIndex] ?? neqParts[0], 10),\n isNull: this.#decodeSampleIsNull(s.sample),\n };\n });\n\n const nonNullSamples = decodedSamples.filter(s => !s.isNull);\n\n if (nonNullSamples.length === 0) {\n // All samples are NULL - return fanout of 0 since NULLs don't match in joins\n return {\n fanout: 0,\n source: 'stat4',\n confidence: 'high',\n };\n }\n\n // Use median of non-NULL fanouts (more robust than average)\n const fanouts = nonNullSamples.map(s => s.fanout).sort((a, b) => a - b);\n const medianFanout =\n fanouts.length % 2 === 0\n ? Math.floor(\n (fanouts[fanouts.length / 2 - 1] + fanouts[fanouts.length / 2]) /\n 2,\n )\n : fanouts[Math.floor(fanouts.length / 2)];\n\n return {\n fanout: medianFanout,\n source: 'stat4',\n confidence: 'high',\n };\n } catch {\n // stat4 table may not exist or query may fail\n return undefined;\n }\n }\n\n /**\n * Gets fanout from sqlite_stat1 average.\n *\n * Note: This includes NULL rows in the calculation and may overestimate\n * fanout for sparse foreign keys.\n *\n * For compound indexes, uses the stat value at the appropriate depth.\n *\n * @param columns Array of column names to get fanout for\n * @returns Fanout result or undefined if stat1 unavailable\n */\n #getFanoutFromStat1(\n tableName: string,\n columns: string[],\n ): FanoutResult | undefined {\n try {\n // Find index containing the columns as a prefix\n const indexInfo = this.#findIndexForColumns(tableName, columns);\n if (!indexInfo) {\n return undefined;\n }\n\n // Query stat1 for this index (using prepared statement)\n const result = this.#stat1Stmt.get(tableName, indexInfo.indexName) as\n | {stat: string}\n | undefined;\n\n if (!result) {\n return undefined;\n }\n\n const parts = result.stat.split(' ');\n // Check if we have enough parts for the requested depth\n if (parts.length < indexInfo.depth + 1) {\n return undefined;\n }\n\n const fanout = parseInt(parts[indexInfo.depth], 10);\n if (isNaN(fanout)) {\n return undefined;\n }\n\n return {\n fanout,\n source: 'stat1',\n confidence: 'med',\n };\n } catch {\n return undefined;\n }\n }\n\n /**\n * Finds an index that can be used to get statistics for column(s).\n *\n * Uses pragma_index_list and pragma_index_info to reliably get index\n * column names, avoiding brittle SQL parsing. Includes all indices:\n * user-created (CREATE INDEX), PRIMARY KEY, and UNIQUE constraints.\n *\n * Uses flexible matching: Finds indexes where ALL columns appear in the\n * first N positions, regardless of order. This works because SQLite statistics\n * at depth N represent the fanout for the combination of the first N columns,\n * and combinations are order-independent.\n *\n * Example:\n * - columns: ['customerId', 'storeId']\n * - Matches: (customerId, storeId, date) at depth 2 ✅\n * - Matches: (storeId, customerId, date) at depth 2 ✅ (flexible order)\n * - Does NOT match: (date, customerId, storeId) ❌ (columns not in first 2 positions)\n * - Does NOT match: (customerId, date, storeId) ❌ (storeId not in first 2 positions)\n *\n * @param columns Array of column names (order-independent for matching)\n * @returns Index info with name and depth, or undefined if no match\n */\n #findIndexForColumns(\n tableName: string,\n columns: string[],\n ): {indexName: string; depth: number} | undefined {\n try {\n // Query returns all columns for all indexes (including PK/UNIQUE) in order\n const rows = this.#indexStmt.all(tableName) as {\n index_name: string;\n seqno: number;\n column_name: string;\n }[];\n\n // Group by index name\n const indexMap = new Map<string, string[]>();\n for (const row of rows) {\n const cols = indexMap.get(row.index_name) ?? [];\n cols.push(row.column_name);\n indexMap.set(row.index_name, cols);\n }\n\n // Check each index for prefix match\n for (const [indexName, indexColumns] of indexMap) {\n if (this.#isPrefixMatch(columns, indexColumns)) {\n return {\n indexName,\n depth: columns.length,\n };\n }\n }\n\n return undefined;\n } catch {\n return undefined;\n }\n }\n\n /**\n * Checks if all queryColumns exist in the first N positions of indexColumns,\n * regardless of order.\n *\n * This allows flexible matching: constraint {a, b} matches both index (a, b, c)\n * and index (b, a, c) at depth 2, since both represent the fanout for the\n * combination of columns a and b.\n *\n * Gaps are NOT allowed: constraint {a, c} does NOT match index (a, b, c)\n * because no depth represents just (a, c) without b. Statistics are cumulative\n * from position 0.\n *\n * @param queryColumns Columns we're looking for (from constraint)\n * @param indexColumns Columns in the index (in order)\n * @returns true if all queryColumns exist in indexColumns[0...queryColumns.length-1]\n */\n #isPrefixMatch(queryColumns: string[], indexColumns: string[]): boolean {\n if (queryColumns.length > indexColumns.length) {\n return false;\n }\n\n // Get the prefix of the index that we're checking against\n const indexPrefix = indexColumns.slice(0, queryColumns.length);\n\n // Normalize to lowercase for case-insensitive comparison\n const indexPrefixLower = new Set(indexPrefix.map(col => col.toLowerCase()));\n const queryColumnsLower = queryColumns.map(col => col.toLowerCase());\n\n // Check if ALL query columns exist in the index prefix\n return queryColumnsLower.every(queryCol => indexPrefixLower.has(queryCol));\n }\n\n /**\n * Decodes a sqlite_stat4 sample value to check if it's NULL.\n *\n * SQLite record format (simplified):\n * - Varint: header size\n * - Serial types for each column (one byte each typically)\n * - Actual data\n *\n * Serial type 0 = NULL\n * Serial type 1 = 8-bit int\n * Serial type 2 = 16-bit int\n * Serial type 3 = 24-bit int\n * etc.\n *\n * We only need to check the first column's serial type.\n *\n * @param sample Binary-encoded sample from stat4\n * @returns true if the sample value is NULL\n */\n #decodeSampleIsNull(sample: Buffer): boolean {\n if (sample.length === 0) {\n return true;\n }\n\n // Read header size (varint - simplified: assume single byte)\n const headerSize = sample[0];\n\n if (headerSize === 0 || headerSize >= sample.length) {\n return true;\n }\n\n // Read first serial type (at position 1)\n const serialType = sample[1];\n\n // Serial type 0 = NULL\n return serialType === 0;\n }\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"sqlite-stat-fanout.js","names":["#db","#defaultFanout","#cache","#stat4Stmt","#stat1Stmt","#indexStmt","#getFanoutFromStat4","#getFanoutFromStat1","#findIndexForColumns","#decodeSampleIsNull","#isPrefixMatch"],"sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"sourcesContent":["import type {Database} from './db.ts';\n\n/**\n * Result of fanout calculation from SQLite statistics.\n */\nexport interface FanoutResult {\n /**\n * The fanout value (average rows per distinct value of the join column).\n * For non-NULL joins, this represents how many child rows exist per parent key.\n */\n fanout: number;\n confidence: 'high' | 'med' | 'none';\n\n /**\n * Source of the fanout calculation.\n * - 'stat4': From sqlite_stat4 histogram (most accurate, excludes NULLs)\n * - 'stat1': From sqlite_stat1 average (includes NULLs, may overestimate)\n * - 'default': Fallback constant when statistics unavailable\n */\n source: 'stat4' | 'stat1' | 'default';\n}\n\n/**\n * Sample from sqlite_stat4 histogram.\n */\ninterface Stat4Sample {\n /** \"N1 N2\" = rows equal to sample (N1=first col, N2=if composite) */\n neq: string;\n /** \"N1 N2\" = rows less than sample */\n nlt: string;\n /** \"N1 N2\" = distinct values less than sample */\n ndlt: string;\n /** The actual sample value (binary encoded) */\n sample: Buffer;\n}\n\n/**\n * Computes join fanout factors from SQLite statistics tables.\n *\n * Fanout is the average number of child rows per distinct parent key value,\n * used to estimate join cardinality in query planning.\n *\n * ## Problem\n *\n * sqlite_stat1 includes NULL rows in its calculation, which can significantly\n * overestimate fanout for sparse foreign keys:\n *\n * ```\n * Example: 100 tasks, 20 with project_id, 80 with NULL\n * - stat1 reports: \"100 17\" → fanout = 17 (WRONG - includes NULLs)\n * - stat4 shows: NULL samples with fanout=80, non-NULL samples with fanout=4\n * - True fanout: 4 (CORRECT)\n * ```\n *\n * ## Solution\n *\n * This class uses sqlite_stat4 histogram to separate NULL and non-NULL samples,\n * providing accurate fanout for non-NULL joins.\n *\n * ## Usage\n *\n * ```typescript\n * const calculator = new SQLiteStatFanout(db);\n *\n * // Get fanout for posts.userId → users.id join\n * const result = calculator.getFanout('posts', 'userId');\n *\n * if (result.source === 'stat4') {\n * // Accurate: excludes NULLs, samples actual distribution\n * console.log(`Fanout: ${result.fanout} (from stat4)`);\n * } else if (result.source === 'stat1') {\n * // Conservative: includes NULLs, may overestimate\n * console.log(`Fanout: ${result.fanout} (from stat1, includes NULLs)`);\n * } else {\n * // Fallback: no statistics available\n * console.log(`Fanout: ${result.fanout} (default estimate)`);\n * }\n * ```\n *\n * ## Requirements\n *\n * - SQLite compiled with ENABLE_STAT4 (most builds include this)\n * - `ANALYZE` command run on the database\n * - Index exists on the join column\n *\n * @see https://sqlite.org/fileformat2.html#stat4tab\n * @see packages/zql/src/planner/SELECTIVITY_PLAN.md\n */\nexport class SQLiteStatFanout {\n readonly #db: Database;\n readonly #defaultFanout: number;\n\n /**\n * Cache of fanout results by table and columns.\n * Key format: \"tableName:col1,col2,col3\" (sorted alphabetically)\n */\n readonly #cache = new Map<string, FanoutResult>();\n\n /**\n * Prepared statements for querying SQLite statistics tables.\n * Prepared once in constructor for performance.\n */\n readonly #stat4Stmt: ReturnType<Database['prepare']>;\n readonly #stat1Stmt: ReturnType<Database['prepare']>;\n readonly #indexStmt: ReturnType<Database['prepare']>;\n\n /**\n * Creates a new fanout calculator.\n *\n * @param db Database instance\n * @param defaultFanout Default fanout when statistics unavailable (default: 3)\n * - 1: Conservative (assumes FK relationships)\n * - 3: Moderate (recommended, safe middle ground)\n * - 10: SQLite's default (optimistic)\n */\n constructor(db: Database, defaultFanout = 3) {\n this.#db = db;\n this.#defaultFanout = defaultFanout;\n\n // Prepare SQL statements once for reuse across multiple getFanout() calls\n this.#stat4Stmt = this.#db.prepare(`\n SELECT neq, nlt, ndlt, sample\n FROM sqlite_stat4\n WHERE tbl = ? AND idx = ?\n ORDER BY nlt\n `);\n\n this.#stat1Stmt = this.#db.prepare(`\n SELECT stat\n FROM sqlite_stat1\n WHERE tbl = ? AND idx = ?\n `);\n\n this.#indexStmt = this.#db.prepare(`\n SELECT il.name as index_name, ii.seqno, ii.name as column_name\n FROM pragma_index_list(?) il\n JOIN pragma_index_info(il.name) ii\n WHERE il.partial = 0\n ORDER BY il.seq, ii.seqno\n `);\n }\n\n /**\n * Gets the fanout factor for join column(s).\n *\n * Fanout = average number of child rows per distinct parent key value(s).\n *\n * ## Strategy\n *\n * 1. Try sqlite_stat4 (best): Histogram with separate NULL/non-NULL samples\n * 2. Fallback to sqlite_stat1: Average across all rows (includes NULLs)\n * 3. Fallback to default: When no statistics available\n *\n * ## Compound Indexes\n *\n * For multi-column joins, finds indexes where ALL columns appear as an\n * exact prefix. Uses the appropriate depth in stat1/stat4.\n *\n * Example:\n * - Columns: `['customerId', 'storeId']`\n * - Matches index: `(customerId, storeId, date)` at depth 2\n * - Uses stat1 parts[2] or stat4 neq[1] for accurate fanout\n *\n * ## Caching\n *\n * Results are cached per (table, columns) combination. Clear the cache if\n * you run ANALYZE to update statistics.\n *\n * @param tableName Table containing the join column(s)\n * @param columns Array of column names (one or more columns)\n * @returns Fanout result with value and source\n */\n getFanout(tableName: string, columns: string[]): FanoutResult {\n // Cache key uses sorted columns for consistency\n const cacheKey = `${tableName}:${columns.toSorted().join(',')}`;\n const cached = this.#cache.get(cacheKey);\n if (cached) {\n return cached;\n }\n\n // Strategy 1: Try stat4 first (most accurate)\n // NOTE: columns are NOT sorted - preserves Object.keys() order from constraint\n // Matching is order-independent (flexible), but we keep original order for consistency\n const stat4Result = this.#getFanoutFromStat4(tableName, columns);\n if (stat4Result) {\n this.#cache.set(cacheKey, stat4Result);\n return stat4Result;\n }\n\n // Strategy 2: Fallback to stat1 (includes NULLs)\n const stat1Result = this.#getFanoutFromStat1(tableName, columns);\n if (stat1Result) {\n this.#cache.set(cacheKey, stat1Result);\n return stat1Result;\n }\n\n // Strategy 3: Use default\n const defaultResult: FanoutResult = {\n fanout: this.#defaultFanout,\n confidence: 'none',\n source: 'default',\n };\n this.#cache.set(cacheKey, defaultResult);\n return defaultResult;\n }\n\n /**\n * Clears the fanout cache.\n * Call this after running ANALYZE to pick up updated statistics.\n */\n clearCache(): void {\n this.#cache.clear();\n }\n\n /**\n * Gets fanout from sqlite_stat4 histogram.\n *\n * Queries stat4 samples, decodes to identify NULLs, and returns\n * the median fanout of non-NULL samples.\n *\n * For compound indexes, uses the neq value at the appropriate depth.\n *\n * @param columns Array of column names to get fanout for\n * @returns Fanout result or undefined if stat4 unavailable\n */\n #getFanoutFromStat4(\n tableName: string,\n columns: string[],\n ): FanoutResult | undefined {\n try {\n // Find index containing the columns as a prefix\n const indexInfo = this.#findIndexForColumns(tableName, columns);\n if (!indexInfo) {\n return undefined;\n }\n\n // Query stat4 samples for this index (using prepared statement)\n const samples = this.#stat4Stmt.all(\n tableName,\n indexInfo.indexName,\n ) as Stat4Sample[];\n\n if (samples.length === 0) {\n return undefined;\n }\n\n // Decode samples and separate NULL from non-NULL\n // Use depth-1 for neq array index (depth is 1-based, array is 0-based)\n const neqIndex = indexInfo.depth - 1;\n const decodedSamples = samples.map(s => {\n const neqParts = s.neq.split(' ');\n return {\n fanout: parseInt(neqParts[neqIndex] ?? neqParts[0], 10),\n isNull: this.#decodeSampleIsNull(s.sample),\n };\n });\n\n const nonNullSamples = decodedSamples.filter(s => !s.isNull);\n\n if (nonNullSamples.length === 0) {\n // All samples are NULL - return fanout of 0 since NULLs don't match in joins\n return {\n fanout: 0,\n source: 'stat4',\n confidence: 'high',\n };\n }\n\n // Use median of non-NULL fanouts (more robust than average)\n const fanouts = nonNullSamples.map(s => s.fanout).sort((a, b) => a - b);\n const medianFanout =\n fanouts.length % 2 === 0\n ? Math.floor(\n (fanouts[fanouts.length / 2 - 1] + fanouts[fanouts.length / 2]) /\n 2,\n )\n : fanouts[Math.floor(fanouts.length / 2)];\n\n return {\n fanout: medianFanout,\n source: 'stat4',\n confidence: 'high',\n };\n } catch {\n // stat4 table may not exist or query may fail\n return undefined;\n }\n }\n\n /**\n * Gets fanout from sqlite_stat1 average.\n *\n * Note: This includes NULL rows in the calculation and may overestimate\n * fanout for sparse foreign keys.\n *\n * For compound indexes, uses the stat value at the appropriate depth.\n *\n * @param columns Array of column names to get fanout for\n * @returns Fanout result or undefined if stat1 unavailable\n */\n #getFanoutFromStat1(\n tableName: string,\n columns: string[],\n ): FanoutResult | undefined {\n try {\n // Find index containing the columns as a prefix\n const indexInfo = this.#findIndexForColumns(tableName, columns);\n if (!indexInfo) {\n return undefined;\n }\n\n // Query stat1 for this index (using prepared statement)\n const result = this.#stat1Stmt.get(tableName, indexInfo.indexName) as\n | {stat: string}\n | undefined;\n\n if (!result) {\n return undefined;\n }\n\n const parts = result.stat.split(' ');\n // Check if we have enough parts for the requested depth\n if (parts.length < indexInfo.depth + 1) {\n return undefined;\n }\n\n const fanout = parseInt(parts[indexInfo.depth], 10);\n if (isNaN(fanout)) {\n return undefined;\n }\n\n return {\n fanout,\n source: 'stat1',\n confidence: 'med',\n };\n } catch {\n return undefined;\n }\n }\n\n /**\n * Finds an index that can be used to get statistics for column(s).\n *\n * Uses pragma_index_list and pragma_index_info to reliably get index\n * column names, avoiding brittle SQL parsing. Includes all indices:\n * user-created (CREATE INDEX), PRIMARY KEY, and UNIQUE constraints.\n *\n * Uses flexible matching: Finds indexes where ALL columns appear in the\n * first N positions, regardless of order. This works because SQLite statistics\n * at depth N represent the fanout for the combination of the first N columns,\n * and combinations are order-independent.\n *\n * Example:\n * - columns: ['customerId', 'storeId']\n * - Matches: (customerId, storeId, date) at depth 2 ✅\n * - Matches: (storeId, customerId, date) at depth 2 ✅ (flexible order)\n * - Does NOT match: (date, customerId, storeId) ❌ (columns not in first 2 positions)\n * - Does NOT match: (customerId, date, storeId) ❌ (storeId not in first 2 positions)\n *\n * @param columns Array of column names (order-independent for matching)\n * @returns Index info with name and depth, or undefined if no match\n */\n #findIndexForColumns(\n tableName: string,\n columns: string[],\n ): {indexName: string; depth: number} | undefined {\n try {\n // Query returns all columns for all indexes (including PK/UNIQUE) in order\n const rows = this.#indexStmt.all(tableName) as {\n index_name: string;\n seqno: number;\n column_name: string;\n }[];\n\n // Group by index name\n const indexMap = new Map<string, string[]>();\n for (const row of rows) {\n const cols = indexMap.get(row.index_name) ?? [];\n cols.push(row.column_name);\n indexMap.set(row.index_name, cols);\n }\n\n // Check each index for prefix match\n for (const [indexName, indexColumns] of indexMap) {\n if (this.#isPrefixMatch(columns, indexColumns)) {\n return {\n indexName,\n depth: columns.length,\n };\n }\n }\n\n return undefined;\n } catch {\n return undefined;\n }\n }\n\n /**\n * Checks if all queryColumns exist in the first N positions of indexColumns,\n * regardless of order.\n *\n * This allows flexible matching: constraint {a, b} matches both index (a, b, c)\n * and index (b, a, c) at depth 2, since both represent the fanout for the\n * combination of columns a and b.\n *\n * Gaps are NOT allowed: constraint {a, c} does NOT match index (a, b, c)\n * because no depth represents just (a, c) without b. Statistics are cumulative\n * from position 0.\n *\n * @param queryColumns Columns we're looking for (from constraint)\n * @param indexColumns Columns in the index (in order)\n * @returns true if all queryColumns exist in indexColumns[0...queryColumns.length-1]\n */\n #isPrefixMatch(queryColumns: string[], indexColumns: string[]): boolean {\n if (queryColumns.length > indexColumns.length) {\n return false;\n }\n\n // Get the prefix of the index that we're checking against\n const indexPrefix = indexColumns.slice(0, queryColumns.length);\n\n // Normalize to lowercase for case-insensitive comparison\n const indexPrefixLower = new Set(indexPrefix.map(col => col.toLowerCase()));\n const queryColumnsLower = queryColumns.map(col => col.toLowerCase());\n\n // Check if ALL query columns exist in the index prefix\n return queryColumnsLower.every(queryCol => indexPrefixLower.has(queryCol));\n }\n\n /**\n * Decodes a sqlite_stat4 sample value to check if it's NULL.\n *\n * SQLite record format (simplified):\n * - Varint: header size\n * - Serial types for each column (one byte each typically)\n * - Actual data\n *\n * Serial type 0 = NULL\n * Serial type 1 = 8-bit int\n * Serial type 2 = 16-bit int\n * Serial type 3 = 24-bit int\n * etc.\n *\n * We only need to check the first column's serial type.\n *\n * @param sample Binary-encoded sample from stat4\n * @returns true if the sample value is NULL\n */\n #decodeSampleIsNull(sample: Buffer): boolean {\n if (sample.length === 0) {\n return true;\n }\n\n // Read header size (varint - simplified: assume single byte)\n const headerSize = sample[0];\n\n if (headerSize === 0 || headerSize >= sample.length) {\n return true;\n }\n\n // Read first serial type (at position 1)\n const serialType = sample[1];\n\n // Serial type 0 = NULL\n return serialType === 0;\n }\n}\n"],"mappings":"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"}
|
|
@@ -55,7 +55,7 @@ export declare class TableSource implements Source {
|
|
|
55
55
|
getRow(rowKey: Row): Row | undefined;
|
|
56
56
|
}
|
|
57
57
|
export declare function toSQLiteTypes(columns: readonly string[], row: Row, columnTypes: Record<string, SchemaValue>): readonly unknown[];
|
|
58
|
-
export declare function toSQLiteTypeName(type: ValueType): "
|
|
58
|
+
export declare function toSQLiteTypeName(type: ValueType): "NULL" | "INTEGER" | "REAL" | "TEXT";
|
|
59
59
|
export declare function fromSQLiteTypes(valueTypes: Record<string, SchemaValue>, row: Row, tableName: string): Row;
|
|
60
60
|
export declare class UnsupportedValueError extends Error {
|
|
61
61
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"table-source.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/table-source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,+BAA+B,CAAC;AAK7D,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAC,GAAG,EAAQ,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AACvE,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACV,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,yCAAyC,CAAC;AAkB3E,OAAO,EACL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,6BAA6B,CAAC;AAExD,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,SAAS,CAAC;AAoBjD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,YAAW,MAAM;;IAexC;;;;;OAKG;gBAED,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,UAAU,EAAE,UAAU,EACtB,WAAW,gBAAc;IAiB3B,IAAI,WAAW;;;;MAMd;IAED;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,QAAQ;IA4FlB,OAAO,CACL,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,OAAO,CAAC,EAAE,SAAS,EACnB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,KAAK,CAAC,EAAE,aAAa;IA8CvB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG;IAqIzB,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC;IAQ3C,OAAO,CAAC,MAAM,EAAE,YAAY;IAqG7B;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS;CA+BrC;
|
|
1
|
+
{"version":3,"file":"table-source.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/table-source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,+BAA+B,CAAC;AAK7D,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAC,GAAG,EAAQ,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AACvE,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACV,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,yCAAyC,CAAC;AAkB3E,OAAO,EACL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,6BAA6B,CAAC;AAExD,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,SAAS,CAAC;AAoBjD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,YAAW,MAAM;;IAexC;;;;;OAKG;gBAED,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,UAAU,EAAE,UAAU,EACtB,WAAW,gBAAc;IAiB3B,IAAI,WAAW;;;;MAMd;IAED;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,QAAQ;IA4FlB,OAAO,CACL,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,OAAO,CAAC,EAAE,SAAS,EACnB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,KAAK,CAAC,EAAE,aAAa;IA8CvB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG;IAqIzB,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC;IAQ3C,OAAO,CAAC,MAAM,EAAE,YAAY;IAqG7B;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS;CA+BrC;AA8BD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,GAAG,EACR,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACvC,SAAS,OAAO,EAAE,CAEpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,wCAa/C;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACvC,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,GAChB,GAAG,CAaL;AAwCD,qBAAa,qBAAsB,SAAQ,KAAK;CAAG"}
|
|
@@ -246,7 +246,8 @@ function getUniqueIndexes(db, tableName) {
|
|
|
246
246
|
JOIN pragma_index_info(idx.name) as col
|
|
247
247
|
WHERE idx.tbl_name = ${tableName} AND
|
|
248
248
|
idx.type = 'index' AND
|
|
249
|
-
info."unique" != 0
|
|
249
|
+
info."unique" != 0 AND
|
|
250
|
+
info.partial = 0
|
|
250
251
|
GROUP BY idx.name
|
|
251
252
|
ORDER BY idx.name`);
|
|
252
253
|
const indexes = db.prepare(sqlAndBindings.text).all(...sqlAndBindings.values);
|