@sandboxxjs/state 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+* Type definitions for @sandboxxjs/state
+*/
+/**
+* Minimal Sandbox interface that State layer needs
+*/
+interface Sandbox {
+	shell(command: string): Promise<ShellResult>;
+}
+interface ShellResult {
+	success: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+	executionTime: number;
+}
+/**
+* File system interface
+*/
+interface FileSystem {
+	read(path: string): Promise<string>;
+	write(path: string, data: string): Promise<void>;
+	list(path: string): Promise<string[]>;
+	exists(path: string): Promise<boolean>;
+	delete(path: string): Promise<void>;
+}
+/**
+* Environment variables interface
+*/
+interface Environment {
+	get(key: string): string | undefined;
+	set(key: string, value: string): void;
+	has(key: string): boolean;
+	delete(key: string): void;
+	keys(): string[];
+	all(): Record<string, string>;
+}
+/**
+* Key-value storage interface
+*/
+interface Storage {
+	getItem(key: string): string | null;
+	setItem(key: string, value: string): void;
+	removeItem(key: string): void;
+	clear(): void;
+	keys(): string[];
+}
+/**
+* StateLog type (opaque - use buildStateLog to create)
+*/
+type StateLog = {
+	fs: {
+		write(path: string, data: string): StateLog
+		delete(path: string): StateLog
+	}
+	env: {
+		set(key: string, value: string): StateLog
+		delete(key: string): StateLog
+	}
+	storage: {
+		set(key: string, value: string): StateLog
+		delete(key: string): StateLog
+		clear(): StateLog
+	}
+	getEntries(): StateLogEntry[]
+	toJSON(): string
+	compact(): StateLog
+};
+interface StateLogEntry {
+	op: string;
+	args: Record<string, unknown>;
+}
+/**
+* State capability (fs + env + storage)
+*/
+interface WithState {
+	fs: FileSystem;
+	env: Environment;
+	storage: Storage;
+	getStateLog?(): StateLog;
+}
+declare class StateFS implements FileSystem {
+	private sandbox;
+	constructor(sandbox: Sandbox);
+	read(path: string): Promise<string>;
+	write(path: string, data: string): Promise<void>;
+	exists(path: string): Promise<boolean>;
+	delete(path: string): Promise<void>;
+	list(path: string): Promise<string[]>;
+}
+declare class StateEnv implements Environment {
+	private vars;
+	constructor(initial?: Record<string, string>);
+	get(key: string): string | undefined;
+	set(key: string, value: string): void;
+	has(key: string): boolean;
+	delete(key: string): void;
+	keys(): string[];
+	all(): Record<string, string>;
+}
+declare class StateStorage implements Storage {
+	private data;
+	constructor(initial?: Record<string, string>);
+	getItem(key: string): string | null;
+	setItem(key: string, value: string): void;
+	removeItem(key: string): void;
+	clear(): void;
+	keys(): string[];
+}
+/**
+* StateLog - Records state operations for replay and persistence
+*/
+interface StateLogEntry2 {
+	op: string;
+	args: Record<string, unknown>;
+}
+declare class StateLog2 {
+	private entries;
+	/**
+	* File system operations
+	*/
+	fs: {
+		write: (path: string, data: string) => StateLog2
+		delete: (path: string) => StateLog2
+	};
+	/**
+	* Environment variable operations
+	*/
+	env: {
+		set: (key: string, value: string) => StateLog2
+		delete: (key: string) => StateLog2
+	};
+	/**
+	* Storage operations
+	*/
+	storage: {
+		set: (key: string, value: string) => StateLog2
+		delete: (key: string) => StateLog2
+		clear: () => StateLog2
+	};
+	/**
+	* Record a raw entry (used by recording proxy)
+	* @internal
+	*/
+	recordEntry(op: string, args: Record<string, unknown>): StateLog2;
+	/**
+	* Get all entries
+	*/
+	getEntries(): StateLogEntry2[];
+	/**
+	* Serialize to JSON string
+	*/
+	toJSON(): string;
+	/**
+	* Deserialize from JSON string (internal use)
+	*/
+	static fromJSON(json: string): StateLog2;
+	/**
+	* Create from entries array (internal use)
+	*/
+	static fromEntries(entries: StateLogEntry2[]): StateLog2;
+	/**
+	* Compact the log by merging redundant operations
+	*/
+	compact(): StateLog2;
+}
+/**
+* Build a new StateLog (functional API)
+*/
+declare function buildStateLog(): StateLog2;
+/**
+* Load StateLog from JSON string
+*/
+declare function loadStateLog(json: string): StateLog2;
+/**
+* Replay StateLog operations to a target
+*/
+declare function replayStateLog(log: StateLog, target: WithState): Promise<void>;
+interface CreateStateOptions {
+	/** Sandbox instance for fs operations */
+	sandbox: Sandbox;
+	/** Initial environment variables */
+	env?: Record<string, string>;
+	/** Enable recording to StateLog */
+	enableRecord?: boolean;
+}
+interface StateResult {
+	fs: FileSystem;
+	env: Environment;
+	storage: Storage;
+	stateLog?: StateLog;
+}
+/**
+* Create state instances
+*/
+declare function createState(options: CreateStateOptions): StateResult;
+interface StateStore {
+	saveLog(key: string, data: string): Promise<void>;
+	loadLog(key: string): Promise<string | null>;
+	deleteLog(key: string): Promise<void>;
+	listLogs(): Promise<string[]>;
+	saveBlob(ref: string, data: Buffer): Promise<void>;
+	loadBlob(ref: string): Promise<Buffer | null>;
+	deleteBlob(ref: string): Promise<void>;
+}
+interface StateStoreOptions {
+	type: "memory" | "resourcex";
+}
+/**
+* Create a StateStore instance
+*/
+declare function createStateStore(options: StateStoreOptions): StateStore;
+interface AssetsSandbox {
+	upload(data: Buffer, remotePath: string): Promise<void>;
+	download(remotePath: string): Promise<Buffer>;
+}
+interface StateAssets {
+	uploadBuffer(data: Buffer, remotePath: string): Promise<string>;
+	downloadBuffer(remotePath: string, options?: {
+		persist?: boolean
+	}): Promise<Buffer | string>;
+	list(): string[];
+}
+interface CreateStateAssetsOptions {
+	sandbox: AssetsSandbox;
+	store: StateStore;
+}
+/**
+* Create StateAssets instance
+*/
+declare function createStateAssets(options: CreateStateAssetsOptions): StateAssets;
+/**
+* Error types for @sandboxxjs/state
+*/
+declare class StateError extends Error {
+	constructor(message: string);
+}
+declare class FileSystemError extends StateError {
+	constructor(message: string);
+}
+export { replayStateLog, loadStateLog, createStateStore, createStateAssets, createState, buildStateLog, WithState, Storage, StateStoreOptions, StateStore, StateStorage, StateResult, StateLogEntry, StateLog, StateFS, StateError, StateEnv, StateAssets, ShellResult, Sandbox, FileSystemError, FileSystem, Environment, CreateStateOptions, AssetsSandbox };