@fadhilp/stateql 0.2.2 → 0.3.1

package/README.md

@@ -193,7 +193,12 @@ with `as`. Database commands may set `timeout_ms`; otherwise they use the
 30-second default.
 
 State metadata lives under `STQL_HOME`, or the platform data directory when
-unset. Set `STQL_SESSION` to select a named session.
+unset. Set `STQL_SESSION` to select a named session and `STQL_ACTOR` to select
+an attached actor for CLI invocations. A session is a shared workspace:
+attached actors reuse its connection, handles, aliases, cache, and
+state version, while plans and staged transactions remain owned by their
+creating actor. Callers that omit `actor` keep the legacy behavior where the
+actor ID is the session name.
 
 Read cache entries expire after five minutes; materialized handles expire after
 24 hours. Expired results and plans are deleted when StateQL next opens. Queries
@@ -233,8 +238,9 @@ 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",
+  actor: "pi-session-id",
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
 });
@@ -250,3 +256,14 @@ 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
+an actor before that actor opens an existing workspace. Integrations should ask
+for user confirmation before changing membership or the shared connection.

package/dist/src/cli.js

@@ -49,6 +49,7 @@ const stateql = new StateQL({
     ...(values["timeout-ms"] === undefined
         ? {}
         : { timeoutMs: Number(values["timeout-ms"]) }),
+    ...(process.env.STQL_ACTOR ? { actor: process.env.STQL_ACTOR } : {}),
     signal: abortController.signal,
 });
 try {

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/response-data.js

@@ -18,6 +18,7 @@ export function profileData(profile) {
 export function operationData(operation) {
     return {
         operation_id: operation.id,
+        actor_id: operation.actor_id,
         statement_type: operation.statement_type,
         affected_rows: operation.affected_rows,
         status: operation.status,
@@ -32,6 +33,7 @@ export function transactionData(transaction, statements) {
     return {
         transaction_id: transaction.id,
         state: transaction.state,
+        owner_actor_id: transaction.owner_actor_id,
         connection_id: transaction.connection_id,
         statements,
         pending_writes: transaction.state === "active" ? statements : 0,

package/dist/src/stateql.d.ts

@@ -1,7 +1,9 @@
-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;
     private readonly previewRows;
     private readonly cacheTtlSeconds;
     private readonly resultTtlSeconds;
@@ -23,6 +25,10 @@ export declare class StateQL {
         historyLimit?: number;
     }): StateQLSnapshot;
     status(): Promise<Response<unknown>>;
+    linkActor(session: string, actorId: string): Promise<Response<unknown>>;
+    unlinkActor(session: string, actorId: string): Promise<Response<unknown>>;
+    listActors(session: string): Promise<Response<unknown>>;
+    resolveActor(actorId: string): Promise<Response<unknown>>;
     startSession(name: string): Promise<Response<unknown>>;
     listSessions(): Promise<Response<unknown>>;
     showSession(idOrName?: string): Promise<Response<unknown>>;
@@ -58,6 +64,9 @@ export declare class StateQL {
     private requireResult;
     private requireConnection;
     private requireActiveTransaction;
+    private requireSelectedSession;
+    private validateActorId;
+    private throwMembershipDenied;
     private executionContext;
     private resultData;
     private cacheValid;