@fadhilp/stateql 0.2.0 → 0.3.0

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
@@ -235,6 +240,8 @@ import { StateQL } from "@fadhilp/stateql";
 
 const stateql = new StateQL({
   home: "./.stql",
+  session: "shared-workspace",
+  actor: "pi-session-id",
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
 });
@@ -250,3 +257,9 @@ if (response.ok) {
   });
 }
 ```
+
+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

@@ -36,7 +36,7 @@ const parsed = parseArgs({
 const [command, subcommand, ...rest] = parsed.positionals;
 const values = parsed.values;
 if (values.version) {
-    console.log("0.1.2");
+    console.log(packageVersion());
     process.exit(0);
 }
 if (values.help || !command) {
@@ -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 {
@@ -502,7 +503,7 @@ function extractHandle(data) {
     return undefined;
 }
 function helpText() {
-    return `StateQL 0.1.2
+    return `StateQL ${packageVersion()}
 
 Usage: stql <command> [arguments] [options]
 
@@ -523,3 +524,7 @@ Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
 }
+function packageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}

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, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, Success, } from "./types.js";
+export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, 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,8 @@
-import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions } from "./types.js";
+import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
 export declare class StateQL {
     private readonly store;
     private readonly sessionName;
+    private readonly actorId;
     private readonly previewRows;
     private readonly cacheTtlSeconds;
     private readonly resultTtlSeconds;
@@ -19,7 +20,14 @@ export declare class StateQL {
     showProfile(name: string): Promise<Response<unknown>>;
     removeProfile(name: string): Promise<Response<unknown>>;
     disconnect(): Promise<Response<unknown>>;
+    snapshot(options?: {
+        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>>;
@@ -42,7 +50,9 @@ export declare class StateQL {
     inspect(kind: string, table?: string, options?: ExecutionOptions): Promise<Response<unknown>>;
     plan(sql: string, options?: PlanOptions): Promise<Response<unknown>>;
     apply(planId: string, options?: ExecutionOptions): Promise<Response<unknown>>;
-    history(limit?: number): Promise<Response<unknown>>;
+    history(limit?: number): Promise<Response<{
+        history: HistoryEntry[];
+    }>>;
     capabilities(): Promise<Response<unknown>>;
     executeCommand(command: BatchCommand): Promise<Response<unknown>>;
     batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;
@@ -53,6 +63,9 @@ export declare class StateQL {
     private requireResult;
     private requireConnection;
     private requireActiveTransaction;
+    private requireSelectedSession;
+    private validateActorId;
+    private throwMembershipDenied;
     private executionContext;
     private resultData;
     private cacheValid;