@fadhilp/stateql 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,153 @@
1
+ import { writeFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { nonNegativeInteger, positiveInteger } from "./core.js";
4
+ import { StateQLError } from "./errors.js";
5
+ import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
6
+ import { rowsToCsv } from "./response-data.js";
7
+ import { compactRows, compactValue, hash } from "./util.js";
8
+ export function showResult(core, result) {
9
+ return storedResult(result, core.resultData(result, true));
10
+ }
11
+ export function filterResult(core, source, predicate, options) {
12
+ const columns = core.store.resultColumns(source);
13
+ const filter = prepareFilterStatement(columns, predicate);
14
+ const parameters = options.params ?? [];
15
+ validateFilterParameters(filter, parameters);
16
+ const fingerprint = hash({
17
+ command: "filter",
18
+ source: source.id,
19
+ predicate: filter.normalized,
20
+ parameters,
21
+ });
22
+ const cached = core.store.findResult(fingerprint);
23
+ const reusable = cached !== undefined &&
24
+ cached.session_id === source.session_id &&
25
+ cached.connection_id === source.connection_id &&
26
+ Date.parse(cached.expires_at) > core.now().getTime();
27
+ if (reusable)
28
+ return storedResult(cached, core.resultData(cached, true));
29
+ const saved = core.store.saveResult({
30
+ sessionId: source.session_id,
31
+ connectionId: source.connection_id,
32
+ fingerprint,
33
+ sql: `FILTER ${source.id} WHERE ${predicate.trim()}`,
34
+ parameters,
35
+ rows: filterMaterializedRows(core.store.resultRows(source), filter, parameters),
36
+ columns,
37
+ stateVersion: source.state_version,
38
+ stateSignature: source.state_signature,
39
+ stateConfidence: source.state_confidence,
40
+ expiresAt: source.expires_at,
41
+ });
42
+ return {
43
+ data: core.resultData(saved, false),
44
+ handle: saved.id,
45
+ executed: true,
46
+ stateVersion: saved.state_version,
47
+ confidence: saved.state_confidence,
48
+ };
49
+ }
50
+ export function resultRows(core, result, options) {
51
+ const offset = nonNegativeInteger(options.offset ?? 0, "offset");
52
+ const limit = positiveInteger(options.limit ?? 20, "limit");
53
+ if (limit > 1_000) {
54
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "limit cannot exceed 1000 rows.", { suggestedAction: "Fetch another page or use export." });
55
+ }
56
+ const rows = selectColumns(core.store.resultRows(result).slice(offset, offset + limit), core.store.resultColumns(result), options.columns);
57
+ const next = offset + rows.length;
58
+ return storedResult(result, {
59
+ result_id: result.id,
60
+ offset,
61
+ limit,
62
+ rows: compactRows(rows, core.settings.maxCellCharacters),
63
+ returned: rows.length,
64
+ total: result.row_count,
65
+ truncated: next < result.row_count,
66
+ next_offset: next < result.row_count ? next : null,
67
+ });
68
+ }
69
+ export function countResult(result) {
70
+ return storedResult(result, { result_id: result.id, rows: result.row_count });
71
+ }
72
+ export function resultColumns(core, result) {
73
+ return storedResult(result, { result_id: result.id, columns: core.store.resultColumns(result) });
74
+ }
75
+ export function summarizeResult(core, result) {
76
+ const rows = core.store.resultRows(result);
77
+ return storedResult(result, {
78
+ result_id: result.id,
79
+ total: result.row_count,
80
+ columns: core.store.resultColumns(result).map((column) => summarizeColumn(column.name, rows, core.settings.maxCellCharacters)),
81
+ });
82
+ }
83
+ export function exportResult(core, result, output, format, columns) {
84
+ const resultColumns = core.store.resultColumns(result);
85
+ const rows = selectColumns(core.store.resultRows(result), resultColumns, columns);
86
+ const content = format === "json"
87
+ ? `${JSON.stringify(rows, null, 2)}\n`
88
+ : format === "jsonl"
89
+ ? `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`
90
+ : rowsToCsv(rows, columns ?? resultColumns.map((column) => column.name));
91
+ const path = resolve(output);
92
+ writeFileSync(path, content, "utf8");
93
+ return {
94
+ data: { result_id: result.id, output: path, format, rows: rows.length },
95
+ handle: result.id,
96
+ executed: true,
97
+ };
98
+ }
99
+ function storedResult(result, data) {
100
+ return {
101
+ data,
102
+ handle: result.id,
103
+ cached: true,
104
+ stateVersion: result.state_version,
105
+ confidence: result.state_confidence,
106
+ };
107
+ }
108
+ function selectColumns(rows, available, selected) {
109
+ if (!selected)
110
+ return rows;
111
+ const names = available.map((column) => column.name);
112
+ const unknown = selected.filter((name) => !names.includes(name));
113
+ if (selected.length === 0 || unknown.length > 0) {
114
+ throw new StateQLError("INVALID_COMMAND", unknown.length > 0 ? `Unknown column: ${unknown.join(", ")}.` : "columns cannot be empty.", { suggestedAction: `Use one or more of: ${names.join(", ")}.` });
115
+ }
116
+ // Keep missing keys missing, so MongoDB documents still distinguish missing from null.
117
+ return rows.map((row) => Object.fromEntries(selected.filter((name) => name in row).map((name) => [name, row[name]])));
118
+ }
119
+ function summarizeColumn(name, rows, maxCellCharacters) {
120
+ const values = rows
121
+ .map((row) => row[name])
122
+ .filter((value) => value !== null && value !== undefined);
123
+ const [min, max] = valueRange(values);
124
+ return {
125
+ name,
126
+ nulls: rows.length - values.length,
127
+ distinct: new Set(values.map((value) => JSON.stringify(value))).size,
128
+ min: compactValue(min, maxCellCharacters),
129
+ max: compactValue(max, maxCellCharacters),
130
+ };
131
+ }
132
+ const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
133
+ // Exact numerics (PostgreSQL numeric/bigint, MySQL DECIMAL) arrive as strings, so compare them as numbers.
134
+ function valueRange(values) {
135
+ const numeric = values.every((value) => typeof value === "number" || (typeof value === "string" && NUMERIC_TEXT.test(value)));
136
+ const text = values.every((value) => typeof value === "string");
137
+ if (values.length === 0)
138
+ return [null, null];
139
+ if (!numeric && !text)
140
+ return [null, null];
141
+ const compare = numeric
142
+ ? (left, right) => Number(left) - Number(right)
143
+ : (left, right) => (String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0);
144
+ let min = values[0];
145
+ let max = values[0];
146
+ for (const value of values) {
147
+ if (compare(value, min) < 0)
148
+ min = value;
149
+ if (compare(value, max) > 0)
150
+ max = value;
151
+ }
152
+ return [min, max];
153
+ }
@@ -44,15 +44,22 @@ function execute(request) {
44
44
  switch (request.operation) {
45
45
  case "read": {
46
46
  const [sql, params] = request.args;
47
- const statement = database.prepare(sql);
48
- const rows = bindAll(statement, params);
49
- return {
50
- rows: toJsonSafe(rows),
51
- columns: statement.columns().map((column) => ({
52
- name: column.name,
53
- type: column.type?.toLowerCase() ?? inferType(rows, column.name),
54
- })),
55
- };
47
+ // SQLite itself rejects writes here even if SQL analysis misclassifies a statement.
48
+ database.exec("PRAGMA query_only = ON");
49
+ try {
50
+ const statement = database.prepare(sql);
51
+ const rows = bindAll(statement, params);
52
+ return {
53
+ rows: toJsonSafe(rows),
54
+ columns: statement.columns().map((column) => ({
55
+ name: column.name,
56
+ type: column.type?.toLowerCase() ?? inferType(rows, column.name),
57
+ })),
58
+ };
59
+ }
60
+ finally {
61
+ database.exec("PRAGMA query_only = OFF");
62
+ }
56
63
  }
57
64
  case "write": {
58
65
  if (readOnly)
@@ -1,30 +1,16 @@
1
- import { type TableChange } from "./table-editor.js";
2
- import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, SummaryData, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
1
+ import { type MaterializedPage, type TableRead } from "./panel.js";
2
+ import type { TableChange } from "./table-editor.js";
3
+ import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchOptions, CapabilitiesData, CatalogObject, CloseSessionData, ColumnsData, CommandExecutionContext, CommandOrigin, CommitTransactionData, ConnectionData, ConnectOptions, CountData, DescribeObjectData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, ListObjectsData, ListObjectsFilter, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, ProfileUpdateOptions, PurgeData, QueryOptions, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, SessionData, SessionsData, SessionSummaryData, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusData, SummaryData, TransactionData } from "./types.js";
3
4
  export declare class StateQL {
4
5
  /** Runtime contract marker for passwordRef/password_ref support. */
5
6
  static readonly passwordReferenceVersion: 1;
6
7
  static forActor(options: StateQLActorOptions): StateQL;
7
8
  /** Opens one actor in a named shared workspace for a trusted library host. */
8
9
  static forWorkspace(options: StateQLWorkspaceOptions): StateQL;
10
+ private readonly core;
9
11
  private readonly store;
10
- private readonly sessionName;
11
- private readonly actorId;
12
- private readonly previewRows;
13
- private readonly cacheTtlSeconds;
14
- private readonly resultTtlSeconds;
15
- private readonly maxCellCharacters;
16
- private readonly maxResultRows;
17
- private readonly maxResultBytes;
18
- private readonly timeoutMs;
19
- private readonly credentialTimeoutMs;
20
- private readonly signal?;
21
- private readonly commandContexts;
22
- private readonly credentialResolver?;
23
- private readonly now;
12
+ private readonly panel;
24
13
  private closed;
25
- private readonly tableResults;
26
- private readonly editTokens;
27
- private panelRows?;
28
14
  constructor(options?: StateQLOptions);
29
15
  close(): void;
30
16
  [Symbol.dispose](): void;
@@ -61,12 +47,7 @@ export declare class StateQL {
61
47
  /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
62
48
  readMaterialized(id: string, options?: RowsOptions & {
63
49
  signal?: AbortSignal;
64
- }): RowsData & {
65
- columns: Column[];
66
- row_tokens: Array<string | null>;
67
- writable_columns: string[];
68
- editing_reason?: string;
69
- };
50
+ }): MaterializedPage;
70
51
  /** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
71
52
  serializeResult(id: string, format: "json" | "jsonl" | "csv", signal?: AbortSignal, origin?: CommandOrigin): Promise<Response<{
72
53
  content: string;
@@ -78,14 +59,7 @@ export declare class StateQL {
78
59
  name: string;
79
60
  }, limit?: number, options?: QueryOptions & {
80
61
  origin?: CommandOrigin;
81
- }): Promise<Response<ResultData & {
82
- table: {
83
- schema?: string;
84
- name: string;
85
- };
86
- sample_limit: number;
87
- query: string;
88
- }>>;
62
+ }): Promise<Response<TableRead>>;
89
63
  planTableUpdate(token: string, changes: TableChange, options?: ExecutionOptions & {
90
64
  origin?: CommandOrigin;
91
65
  }): Promise<Response<PlanData>>;
@@ -95,9 +69,6 @@ export declare class StateQL {
95
69
  }>, options?: ExecutionOptions & {
96
70
  origin?: CommandOrigin;
97
71
  }): Promise<Response<PlanData>>;
98
- private editableMetadata;
99
- private panelResult;
100
- private fullResultRows;
101
72
  exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv", columns?: string[]): Promise<Response<ExportData>>;
102
73
  exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
103
74
  mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;
@@ -120,30 +91,8 @@ export declare class StateQL {
120
91
  capabilities(): Promise<Response<CapabilitiesData>>;
121
92
  executeCommand(command: BatchCommand, context?: CommandExecutionContext): Promise<Response<unknown>>;
122
93
  batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;
123
- private performExec;
124
- private performMongoExec;
125
- private performRedisExec;
126
- private performTableBatch;
127
94
  private batchFailure;
128
- private withResult;
129
- private rejectDuringStagedTransaction;
130
- private requireResult;
131
- private requireConnection;
132
- private requireMongoConnection;
133
- private requireRedisConnection;
134
- private rejectMongoSql;
135
- private requireActiveTransaction;
136
95
  private requireSelectedSession;
137
96
  private validateActorId;
138
97
  private validateActorName;
139
- private throwMembershipDenied;
140
- private resolveConnectionSource;
141
- private resolveCredential;
142
- private openAdapter;
143
- private openMongoAdapter;
144
- private openRedisAdapter;
145
- private executionContext;
146
- private resultData;
147
- private cacheValid;
148
- private run;
149
98
  }