@fadhilp/stateql 0.4.4 → 0.5.0

package/dist/src/types.d.ts

@@ -121,6 +121,7 @@ export interface StateQLOptions extends ExecutionOptions {
     maxCellCharacters?: number;
     maxResultRows?: number;
     maxResultBytes?: number;
+    maxStateBytes?: number;
     credentialResolver?: CredentialResolver;
     now?: () => Date;
 }
@@ -160,7 +161,7 @@ export interface PlanOptions extends ExecutionOptions {
     allowUnbounded?: boolean;
     allowDestructive?: boolean;
 }
-export type BatchCommandName = "connect" | "disconnect" | "status" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "apply" | "history" | "receipt" | "capabilities";
+export type BatchCommandName = "connect" | "disconnect" | "status" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
 export interface BatchCommand {
     command: BatchCommandName;
     target?: string;
@@ -184,6 +185,7 @@ export interface BatchCommand {
     limit?: number;
     isolation?: string;
     timeout_ms?: number;
+    scope?: "expired" | "results" | "history" | "all";
 }
 export interface BatchOptions {
     continueOnError?: boolean;
@@ -194,3 +196,239 @@ export interface Column {
     type: string;
 }
 export type Row = Record<string, unknown>;
+/** Data returned by the stable, non-dynamic StateQL public methods. */
+export interface ConnectionData {
+    connection_id: string;
+    driver: Driver;
+    database: string;
+    name: string;
+    profile: string | null;
+    read_only: boolean;
+    state_version: string;
+    state_confidence: StateConfidence;
+}
+export interface ProfileData {
+    profile: string;
+    target: string | null;
+    secret_env: string | null;
+    read_only: boolean;
+}
+export interface ProfilesData {
+    profiles: ProfileData[];
+}
+export interface StatusConnectionData {
+    connection_id: string;
+    name: string;
+    driver: Driver;
+    database: string;
+    read_only: boolean;
+}
+export interface TransactionReferenceData {
+    transaction_id: string;
+    owner_actor_id: string;
+    state: string;
+}
+export interface StatusData {
+    session_id: string;
+    session_name: string;
+    actor_id: string;
+    connection: StatusConnectionData | null;
+    transaction: TransactionReferenceData | null;
+    state_version: string | null;
+}
+export interface ActorLinkData {
+    session_id: string;
+    actor_id: string;
+    linked: boolean;
+}
+export interface ActorUnlinkData {
+    session_id: string;
+    actor_id: string;
+    unlinked: boolean;
+}
+export interface ActorData {
+    actor_id: string;
+    attached_at: string;
+}
+export interface ActorsData {
+    session_id: string;
+    actors: ActorData[];
+}
+export interface ActorResolutionData {
+    actor_id: string;
+    session: {
+        session_id: string;
+        name: string;
+        status: string;
+    } | null;
+}
+export interface SessionData {
+    session_id: string;
+    name: string;
+    state: string;
+    active_connection: string | null;
+    active_transaction: string | null;
+}
+export interface SessionListItem {
+    session_id: string;
+    name: string;
+    status: string;
+    active_connection: string | null;
+    active_transaction: string | null;
+}
+export interface SessionsData {
+    sessions: SessionListItem[];
+}
+export interface RecentResultData {
+    alias: string | null;
+    handle: string;
+    rows: number;
+}
+export interface RecentOperationData {
+    handle: string;
+    actor_id: string;
+    type: string;
+    affected_rows: number | null;
+    status: string;
+}
+export interface SessionSummaryData {
+    session_id: string;
+    name: string;
+    connection: string | null;
+    state_version: string | null;
+    transaction: string | null;
+    known_results: RecentResultData[];
+    recent_operations: RecentOperationData[];
+}
+export interface ResultData {
+    result_id: string;
+    rows: number;
+    columns: Column[];
+    preview: Row[];
+    preview_count: number;
+    truncated: boolean;
+    cached: boolean;
+    duplicate_of?: string;
+    state_version: string;
+    storage: {
+        mode: string;
+        expires_at: string;
+    };
+}
+export interface RowsData {
+    result_id: string;
+    offset: number;
+    limit: number;
+    rows: Row[];
+    returned: number;
+    total: number;
+    truncated: boolean;
+    next_offset: number | null;
+}
+export interface CountData {
+    result_id: string;
+    rows: number;
+}
+export interface ColumnsData {
+    result_id: string;
+    columns: Column[];
+}
+export interface AliasData {
+    alias: string;
+    result_id: string;
+}
+export interface ExportData {
+    result_id: string;
+    output: string;
+    format: "json" | "jsonl" | "csv";
+    rows: number;
+}
+export interface OperationData {
+    operation_id: string;
+    actor_id: string;
+    statement_type: string;
+    affected_rows: number | null;
+    status: string;
+    committed: boolean;
+    transaction_id: string | null;
+    state_version_before: string;
+    state_version_after: string | null;
+    replay_of?: string;
+}
+export interface ExecData extends OperationData {
+    duplicate?: boolean;
+    duplicate_of?: string;
+    duplicate_override?: boolean;
+    idempotency_key?: string;
+}
+export interface TransactionData {
+    transaction_id: string;
+    state: string;
+    owner_actor_id: string;
+    connection_id: string;
+    statements: number;
+    pending_writes: number;
+    start_state_version: string;
+    isolation_level: string;
+    age_ms: number;
+}
+export interface CommitTransactionData {
+    transaction_id: string;
+    state: string;
+    statements_executed: number;
+    affected_rows: number;
+    state_version: string;
+}
+export interface RollbackTransactionData {
+    transaction_id: string;
+    state: string;
+    discarded_statements: number;
+}
+export interface PlanData {
+    plan_id: string;
+    statement_type: string;
+    destructive: boolean;
+    requires_confirmation: boolean;
+    required_overrides: string[];
+    state_version: string;
+    owner_actor_id: string;
+    expires_at: string;
+}
+export interface ApplyData extends ExecData {
+    plan_id: string;
+}
+export interface HistoryData {
+    history: HistoryEntry[];
+}
+export interface DoctorData {
+    integrity: "ok" | "issues";
+    issues: Array<{
+        code: string;
+        record?: string;
+    }>;
+    migrations: string[];
+    storage: {
+        result_bytes: number;
+        results: number;
+        history: number;
+    };
+}
+export interface PurgeData {
+    scope: "expired" | "results" | "history" | "all";
+    deleted: number;
+}
+export interface CapabilitiesData {
+    drivers: Driver[];
+    features: Record<string, boolean>;
+}
+export interface RemovedProfileData {
+    profile: string;
+    removed: boolean;
+}
+export interface DisconnectData {
+    disconnected: boolean;
+}
+export interface CloseSessionData {
+    session_id: string;
+    state: string;
+}

package/dist/src/util.d.ts

@@ -1,8 +1,11 @@
-import type { Row } from "./types.js";
+import type { Column, Row, SqlParameters } from "./types.js";
 export declare function defaultHome(): string;
 export declare function hash(value: unknown): string;
 export declare function stableStringify(value: unknown): string;
-export declare function parseJson<T>(value: string, fallback: T): T;
+export declare function parseJson<T>(value: string, context: string, validate?: (parsed: unknown) => parsed is T): T;
+export declare function isSqlParameters(value: unknown): value is SqlParameters;
+export declare function isRows(value: unknown): value is Row[];
+export declare function isColumns(value: unknown): value is Column[];
 export declare function redact(value: string): string;
 export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
 export declare function toJsonSafe<T>(value: T): T;

package/dist/src/util.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { env, platform } from "node:process";
+import { StateQLError } from "./errors.js";
 export function defaultHome() {
     if (env.STQL_HOME)
         return resolve(env.STQL_HOME);
@@ -25,13 +26,34 @@ function sortValue(value) {
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([key, item]) => [key, sortValue(item)]));
 }
-export function parseJson(value, fallback) {
+export function parseJson(value, context, validate) {
+    let parsed;
     try {
-        return JSON.parse(value);
+        parsed = JSON.parse(value);
     }
     catch {
-        return fallback;
+        throw corruptedState(context);
     }
+    if (validate && !validate(parsed))
+        throw corruptedState(context);
+    return parsed;
+}
+export function isSqlParameters(value) {
+    return Array.isArray(value) || isRecord(value);
+}
+export function isRows(value) {
+    return Array.isArray(value) && value.every(isRecord);
+}
+export function isColumns(value) {
+    return Array.isArray(value) && value.every((column) => isRecord(column) &&
+        typeof column.name === "string" &&
+        typeof column.type === "string");
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function corruptedState(context) {
+    return new StateQLError("STATE_CORRUPTED", `Stored ${context} is corrupted.`, { suggestedAction: "Run stql doctor, then purge the affected data." });
 }
 export function redact(value) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",