@fadhilp/stateql 0.3.0 → 0.3.1

package/README.md

@@ -238,9 +238,8 @@ Interrupted commits remain fail-closed; stale `committing` records become
 ```ts
 import { StateQL } from "@fadhilp/stateql";
 
-const stateql = new StateQL({
+const stateql = StateQL.forActor({
   home: "./.stql",
-  session: "shared-workspace",
   actor: "pi-session-id",
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
@@ -258,6 +257,11 @@ if (response.ok) {
 }
 ```
 
+`StateQL.forActor(...)` resolves the actor's attached session directly from
+StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
+On first use, it creates a legacy-compatible session named after the actor.
+Use `new StateQL({ session, actor })` when the session is already known.
+
 Membership is managed only through the library API, not batch commands:
 `linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
 `listActors(session)`, and `resolveActor(actorId)`. An existing member must link

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
 export { StateQL } from "./stateql.js";
 export { StateQLError, exitCodeFor } from "./errors.js";
-export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";
+export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";

package/dist/src/stateql.d.ts

@@ -1,5 +1,6 @@
-import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
+import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
 export declare class StateQL {
+    static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
     private readonly sessionName;
     private readonly actorId;

package/dist/src/stateql.js

@@ -12,6 +12,23 @@ import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
+    static forActor(options) {
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const now = options.now ?? (() => new Date());
+        const store = new StateStore(options.home ?? defaultHome(), now);
+        try {
+            const session = store.resolveActor(options.actor);
+            if (session)
+                return new StateQL({ ...options, session: session.name });
+            const { actor, ...legacyOptions } = options;
+            return new StateQL({ ...legacyOptions, session: actor });
+        }
+        finally {
+            store.close();
+        }
+    }
     store;
     sessionName;
     actorId;

package/dist/src/types.d.ts

@@ -98,6 +98,9 @@ export interface StateQLOptions extends ExecutionOptions {
     maxResultBytes?: number;
     now?: () => Date;
 }
+export type StateQLActorOptions = Omit<StateQLOptions, "session" | "actor"> & {
+    actor: string;
+};
 export interface QueryOptions extends ExecutionOptions {
     params?: SqlParameters;
     cache?: "auto" | "bypass" | "require";

package/package.json

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