@fadhilp/stateql 0.1.1

package/dist/src/types.d.ts

@@ -0,0 +1,112 @@
+export type Driver = "sqlite" | "postgres";
+export type StateConfidence = "authoritative" | "transaction_snapshot" | "database_reported" | "local" | "ttl_based" | "unknown";
+export interface Warning {
+    code: string;
+    message: string;
+}
+export interface StateQLErrorShape {
+    code: string;
+    message: string;
+    retryable: boolean;
+    executed: boolean;
+    suggested_action?: string;
+    [key: string]: unknown;
+}
+export interface ResponseMeta {
+    duration_ms: number;
+    state_version?: string;
+    state_confidence?: StateConfidence;
+}
+export interface Success<T> {
+    ok: true;
+    command_id: string;
+    session_id: string;
+    data: T;
+    warnings: Warning[];
+    meta: ResponseMeta;
+}
+export interface Failure {
+    ok: false;
+    command_id: string;
+    session_id: string;
+    error: StateQLErrorShape;
+    meta: ResponseMeta;
+}
+export type Response<T> = Success<T> | Failure;
+export type SqlParameters = unknown[] | Record<string, unknown>;
+export interface StateQLOptions {
+    home?: string;
+    session?: string;
+    previewRows?: number;
+    cacheTtlSeconds?: number;
+    resultTtlSeconds?: number;
+    maxCellCharacters?: number;
+    maxResultRows?: number;
+    now?: () => Date;
+}
+export interface QueryOptions {
+    params?: SqlParameters;
+    cache?: "auto" | "bypass" | "require";
+}
+export interface FilterOptions {
+    params?: SqlParameters;
+}
+export interface ExecOptions {
+    params?: SqlParameters;
+    replay?: boolean;
+    idempotencyKey?: string;
+    allowUnbounded?: boolean;
+    allowDestructive?: boolean;
+}
+export interface ConnectOptions {
+    name?: string;
+    readOnly?: boolean;
+    secretEnv?: string;
+    profile?: string;
+}
+export interface ProfileOptions {
+    readOnly?: boolean;
+    secretEnv?: string;
+}
+export interface RowsOptions {
+    offset?: number;
+    limit?: number;
+}
+export interface PlanOptions {
+    params?: SqlParameters;
+    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 interface BatchCommand {
+    command: BatchCommandName;
+    target?: string;
+    sql?: string;
+    where?: string;
+    handle?: string;
+    name?: string;
+    as?: string;
+    kind?: string;
+    table?: string;
+    params?: SqlParameters;
+    cache?: "auto" | "bypass" | "require";
+    read_only?: boolean;
+    secret_env?: string;
+    profile?: string;
+    replay?: boolean;
+    idempotency_key?: string;
+    allow_unbounded?: boolean;
+    allow_destructive?: boolean;
+    offset?: number;
+    limit?: number;
+    isolation?: string;
+}
+export interface BatchOptions {
+    continueOnError?: boolean;
+    maxCommands?: number;
+}
+export interface Column {
+    name: string;
+    type: string;
+}
+export type Row = Record<string, unknown>;

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/util.d.ts

@@ -0,0 +1,8 @@
+import type { Row } 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 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

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { env, platform } from "node:process";
+export function defaultHome() {
+    if (env.STQL_HOME)
+        return resolve(env.STQL_HOME);
+    if (platform === "win32") {
+        return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "stql");
+    }
+    return join(env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "stql");
+}
+export function hash(value) {
+    return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, sortValue(item)]));
+}
+export function parseJson(value, fallback) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function redact(value) {
+    try {
+        const url = new URL(value);
+        if (url.password)
+            url.password = "***";
+        if (url.username)
+            url.username = "***";
+        for (const key of url.searchParams.keys()) {
+            if (/pass|token|secret|key/i.test(key))
+                url.searchParams.set(key, "***");
+        }
+        return url.toString();
+    }
+    catch {
+        return value.replace(/(password|token|secret|api[_-]?key)\s*=\s*([^\s;&]+)/gi, "$1=***");
+    }
+}
+export function compactRows(rows, maxCellCharacters) {
+    return rows.map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [
+        key,
+        compactValue(value, maxCellCharacters),
+    ])));
+}
+function compactValue(value, max) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Buffer.isBuffer(value)) {
+        return { type: "binary", length: value.length };
+    }
+    if (typeof value !== "string" || value.length <= max)
+        return value;
+    return {
+        type: "text",
+        length: value.length,
+        preview: value.slice(0, max),
+    };
+}
+export function toJsonSafe(value) {
+    return JSON.parse(JSON.stringify(value, (_key, item) => typeof item === "bigint" ? item.toString() : item));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@fadhilp/stateql",
+  "version": "0.1.1",
+  "description": "Stateful, agent-oriented database CLI for safe result reuse",
+  "type": "module",
+  "bin": {
+    "stql": "dist/src/cli.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/stateql.test.js",
+    "prepack": "npm test"
+  },
+  "keywords": [
+    "database",
+    "sqlite",
+    "postgresql",
+    "cli",
+    "agents",
+    "sql"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "dependencies": {
+    "node-sql-parser": "^5.4.0",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.5",
+    "typescript": "^7.0.0"
+  }
+}