@orkestrel/workspace 0.0.1

package/dist/src/core/index.d.cts

@@ -0,0 +1,701 @@
+import { DriverInterface } from '@orkestrel/database';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { TableInterface } from '@orkestrel/database';
+
+/** The binary MIME labels supported by a binary {@link FileContent} arm. */
+export declare type BinaryMIME = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+
+/**
+ * Clamp a position to text bounds.
+ *
+ * @param text - The addressed text
+ * @param position - The requested position
+ * @returns The clamped position
+ *
+ * @example
+ * ```ts
+ * clampPosition('ab', { line: 9, column: 9 }) // { line: 1, column: 3 }
+ * ```
+ */
+export declare function clampPosition(text: string, position: Position): Position;
+
+/**
+ * Clamp both positions in a range to text bounds.
+ *
+ * @param text - The addressed text
+ * @param range - The requested range
+ * @returns The clamped range
+ *
+ * @example
+ * ```ts
+ * clampRange('ab', { start: { line: 1, column: 1 }, end: { line: 9, column: 9 } })
+ * ```
+ */
+export declare function clampRange(text: string, range: Range): Range;
+
+/**
+ * Compute the byte size of file content.
+ *
+ * @param content - The content to measure
+ * @returns UTF-8 bytes for text or decoded bytes for binary content
+ *
+ * @example
+ * ```ts
+ * computeSize({ text: 'café', language: 'text' }) // 5
+ * ```
+ */
+export declare function computeSize(content: FileContent): number;
+
+/**
+ * Count the lines in file content.
+ *
+ * @param content - The content to inspect
+ * @returns The text line count, or zero for empty text and binary content
+ *
+ * @example
+ * ```ts
+ * countLines({ text: 'a\nb', language: 'text' }) // 2
+ * ```
+ */
+export declare function countLines(content: FileContent): number;
+
+/**
+ * Create the binary arm of {@link FileContent}.
+ *
+ * @param data - The base64 payload
+ * @param mime - The binary MIME
+ * @returns Binary file content
+ *
+ * @example
+ * ```ts
+ * import { createBinaryContent } from '@orkestrel/workspace'
+ *
+ * createBinaryContent('AAAA', 'image/png')
+ * ```
+ */
+export declare function createBinaryContent(data: string, mime: BinaryMIME): FileContent;
+
+/**
+ * Create a database-backed workspace snapshot store.
+ *
+ * @param driver - The database driver; defaults to an in-memory driver
+ * @returns A workspace store backed by the supplied driver
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseWorkspaceStore } from '@orkestrel/workspace'
+ *
+ * const store = createDatabaseWorkspaceStore()
+ * ```
+ */
+export declare function createDatabaseWorkspaceStore(driver?: DriverInterface): WorkspaceStoreInterface;
+
+/**
+ * Create an immutable file with derived size and line counts.
+ *
+ * @param input - The file path, content, and optional state
+ * @returns A frozen file record
+ *
+ * @example
+ * ```ts
+ * import { createFile, createTextContent } from '@orkestrel/workspace'
+ *
+ * createFile({ path: 'a.txt', content: createTextContent('hello', 'text') })
+ * ```
+ */
+export declare function createFile(input: FileInput): FileInterface;
+
+/**
+ * Create an in-memory workspace snapshot store.
+ *
+ * @returns A process-local workspace store
+ *
+ * @example
+ * ```ts
+ * import { createMemoryWorkspaceStore } from '@orkestrel/workspace'
+ *
+ * const store = createMemoryWorkspaceStore()
+ * ```
+ */
+export declare function createMemoryWorkspaceStore(): WorkspaceStoreInterface;
+
+/**
+ * Create the text arm of {@link FileContent}.
+ *
+ * @param text - The text body
+ * @param language - The language tag
+ * @returns Text file content
+ *
+ * @example
+ * ```ts
+ * import { createTextContent } from '@orkestrel/workspace'
+ *
+ * createTextContent('hello', 'text')
+ * ```
+ */
+export declare function createTextContent(text: string, language: string): FileContent;
+
+/**
+ * Create a workspace.
+ *
+ * @param options - Optional identity, emitter configuration, and initial files
+ * @returns A working workspace
+ *
+ * @example
+ * ```ts
+ * import { createWorkspace } from '@orkestrel/workspace'
+ *
+ * const workspace = createWorkspace()
+ * workspace.write('a.txt', 'hello')
+ * ```
+ */
+export declare function createWorkspace(options?: WorkspaceOptions): WorkspaceInterface;
+
+/**
+ * Create an empty workspace registry.
+ *
+ * @param options - Default event hooks and optional durability
+ * @returns A workspace manager
+ *
+ * @example
+ * ```ts
+ * import { createWorkspaceManager } from '@orkestrel/workspace'
+ *
+ * const manager = createWorkspaceManager()
+ * manager.add()
+ * ```
+ */
+export declare function createWorkspaceManager(options?: WorkspaceManagerOptions): WorkspaceManagerInterface;
+
+/**
+ * A workspace snapshot store over a database table.
+ *
+ * Snapshots occupy one opaque column and are narrowed when read back from the storage boundary.
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseWorkspaceStore } from '@orkestrel/workspace'
+ *
+ * const store = createDatabaseWorkspaceStore()
+ * ```
+ */
+export declare class DatabaseWorkspaceStore implements WorkspaceStoreInterface {
+    #private;
+    /**
+     * Wrap a workspace snapshot table.
+     *
+     * @param table - The table keyed by workspace identifier
+     */
+    constructor(table: TableInterface<WorkspaceSnapshotRow>);
+    get(id: string): Promise<WorkspaceSnapshot | undefined>;
+    set(snapshot: WorkspaceSnapshot): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Compute the decoded byte length of a base64 string.
+ *
+ * @param base64 - The base64 data
+ * @returns The decoded byte count
+ *
+ * @example
+ * ```ts
+ * decodedSize('AAAA') // 3
+ * ```
+ */
+export declare function decodedSize(base64: string): number;
+
+/**
+ * Escape regular-expression metacharacters for literal matching.
+ *
+ * @param value - The literal text
+ * @returns The escaped regular-expression source
+ *
+ * @example
+ * ```ts
+ * escapeRegExp('a.b') // 'a\\.b'
+ * ```
+ */
+export declare function escapeRegExp(value: string): string;
+
+/**
+ * File extensions mapped to language tags for text content.
+ *
+ * Unknown extensions intentionally fall back to `text` in
+ * {@link import('./helpers.js').inferLanguage}.
+ */
+export declare const EXTENSION_LANGUAGES: Readonly<Record<string, string>>;
+
+/**
+ * The immutable content of a file: either text with a language tag or base64 data with a MIME.
+ */
+export declare type FileContent = {
+    readonly text: string;
+    readonly language: string;
+} | {
+    readonly data: string;
+    readonly mime: BinaryMIME;
+};
+
+/** The caller-supplied data used to create an immutable file. */
+export declare interface FileInput {
+    readonly path: string;
+    readonly content: FileContent;
+    readonly state?: FileState;
+}
+
+/** An immutable path-addressed file with derived byte and line counts. */
+export declare interface FileInterface {
+    readonly path: string;
+    readonly content: FileContent;
+    readonly state: FileState;
+    readonly size: number;
+    readonly lines: number;
+}
+
+/** The edit state of an immutable file value. */
+export declare type FileState = 'created' | 'modified';
+
+/**
+ * Infer a language tag from the final file extension.
+ *
+ * @param path - The file path
+ * @returns The mapped language, or `text` when the extension is absent or unknown
+ *
+ * @example
+ * ```ts
+ * inferLanguage('src/main.ts') // 'typescript'
+ * ```
+ */
+export declare function inferLanguage(path: string): string;
+
+/**
+ * Determine whether content is the binary arm.
+ *
+ * @param content - The file content
+ * @returns Whether the content carries base64 data and a MIME
+ *
+ * @example
+ * ```ts
+ * isBinary({ data: 'AAAA', mime: 'image/png' }) // true
+ * ```
+ */
+export declare function isBinary(content: FileContent): content is {
+    readonly data: string;
+    readonly mime: BinaryMIME;
+};
+
+/**
+ * Narrow an unknown value to an immutable file record.
+ *
+ * @param value - The value to inspect
+ * @returns Whether the value has the file shape
+ *
+ * @example
+ * ```ts
+ * isFile({ path: 'a.txt', content: { text: 'a', language: 'text' }, state: 'created', size: 1, lines: 1 })
+ * ```
+ */
+export declare function isFile(value: unknown): value is FileInterface;
+
+/**
+ * Determine whether content is the text arm.
+ *
+ * @param content - The file content
+ * @returns Whether the content carries text and a language
+ *
+ * @example
+ * ```ts
+ * isText({ text: 'hello', language: 'text' }) // true
+ * ```
+ */
+export declare function isText(content: FileContent): content is {
+    readonly text: string;
+    readonly language: string;
+};
+
+/**
+ * Determine whether a 1-based range is structurally valid.
+ *
+ * @param range - The range to inspect
+ * @returns Whether both positions are positive and ordered
+ *
+ * @example
+ * ```ts
+ * isValidRange({ start: { line: 1, column: 1 }, end: { line: 1, column: 2 } }) // true
+ * ```
+ */
+export declare function isValidRange(range: Range): boolean;
+
+/**
+ * Narrow a caught value to a {@link WorkspaceError}.
+ *
+ * @param value - The caught value
+ * @returns Whether the value is a workspace error
+ *
+ * @example
+ * ```ts
+ * if (isWorkspaceError(error)) error.code
+ * ```
+ */
+export declare function isWorkspaceError(value: unknown): value is WorkspaceError;
+
+/**
+ * Narrow an unknown value to a workspace snapshot.
+ *
+ * @param value - The value read from a persistence boundary
+ * @returns Whether the value has the workspace snapshot shape
+ *
+ * @example
+ * ```ts
+ * isWorkspaceSnapshot({ id: 'work', files: [] }) // true
+ * ```
+ */
+export declare function isWorkspaceSnapshot(value: unknown): value is WorkspaceSnapshot;
+
+/**
+ * A process-local workspace snapshot store.
+ *
+ * @example
+ * ```ts
+ * import { MemoryWorkspaceStore } from '@orkestrel/workspace'
+ *
+ * const store = new MemoryWorkspaceStore()
+ * ```
+ */
+export declare class MemoryWorkspaceStore implements WorkspaceStoreInterface {
+    #private;
+    get(id: string): Promise<WorkspaceSnapshot | undefined>;
+    set(snapshot: WorkspaceSnapshot): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Convert a 1-based position to a zero-based string offset.
+ *
+ * @param text - The addressed text
+ * @param position - The requested position
+ * @returns The bounded string offset
+ *
+ * @example
+ * ```ts
+ * offsetAt('ab\ncd', { line: 2, column: 1 }) // 3
+ * ```
+ */
+export declare function offsetAt(text: string, position: Position): number;
+
+/** A 1-based caret position inside text. */
+export declare interface Position {
+    readonly line: number;
+    readonly column: number;
+}
+
+/** A half-open text span whose start is inclusive and end is exclusive. */
+export declare interface Range {
+    readonly start: Position;
+    readonly end: Position;
+}
+
+/**
+ * Assemble a nested range from four 1-based coordinates.
+ *
+ * @param fromLine - The start line
+ * @param fromColumn - The start column
+ * @param toLine - The end line
+ * @param toColumn - The end column
+ * @returns The assembled range without validation
+ *
+ * @example
+ * ```ts
+ * rangeOf(1, 1, 1, 2)
+ * ```
+ */
+export declare function rangeOf(fromLine: number, fromColumn: number, toLine: number, toColumn: number): Range;
+
+/** The content and clamped span returned by a ranged read. */
+export declare interface ReadResult {
+    readonly content: string;
+    readonly range: Range;
+}
+
+/** The tallies produced by a replacement operation. */
+export declare interface ReplaceResult {
+    readonly occurrences: number;
+    readonly files: number;
+}
+
+/** One 1-based search hit and the full line that contains it. */
+export declare interface SearchMatch {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly length: number;
+    readonly content: string;
+}
+
+/**
+ * Search and replacement behavior.
+ *
+ * @remarks
+ * `regex` treats the query as regular-expression source, `sensitive` controls case sensitivity,
+ * and `limit` caps the search or replacement count.
+ */
+export declare interface SearchOptions {
+    readonly regex?: boolean;
+    readonly sensitive?: boolean;
+    readonly limit?: number;
+}
+
+/**
+ * Slice a clamped half-open text range.
+ *
+ * @param text - The source text
+ * @param range - The requested range
+ * @returns The ranged substring
+ *
+ * @example
+ * ```ts
+ * sliceRange('hello', { start: { line: 1, column: 1 }, end: { line: 1, column: 6 } }) // 'hello'
+ * ```
+ */
+export declare function sliceRange(text: string, range: Range): string;
+
+/**
+ * Replace a clamped half-open text range.
+ *
+ * @param text - The source text
+ * @param range - The requested range
+ * @param replacement - The replacement text
+ * @returns The spliced text
+ *
+ * @example
+ * ```ts
+ * spliceRange('hello', { start: { line: 1, column: 1 }, end: { line: 1, column: 6 } }, 'bye')
+ * ```
+ */
+export declare function spliceRange(text: string, range: Range, replacement: string): string;
+
+/**
+ * A mutable path-keyed editing surface over immutable files.
+ *
+ * Whole-file edits create text files, ranged edits operate only on existing text files, and
+ * binary files remain available through construction-time hydration. Mutations emit after the
+ * registry has changed.
+ *
+ * @example
+ * ```ts
+ * import { Workspace } from '@orkestrel/workspace'
+ *
+ * const workspace = new Workspace()
+ * workspace.write('notes.txt', 'hello')
+ * workspace.append('notes.txt', ' world')
+ * workspace.read('notes.txt') // 'hello world'
+ * ```
+ */
+export declare class Workspace implements WorkspaceInterface {
+    #private;
+    /**
+     * Create a workspace.
+     *
+     * @param options - Optional identity, emitter configuration, and initial files
+     */
+    constructor(options?: WorkspaceOptions);
+    get id(): string;
+    get emitter(): EmitterInterface<WorkspaceEventMap>;
+    get count(): number;
+    file(path: string): FileInterface | undefined;
+    files(): readonly FileInterface[];
+    read(path: string): string | undefined;
+    read(path: string, range: Range): ReadResult | undefined;
+    read(paths: readonly string[]): Readonly<Record<string, string>>;
+    has(path: string): boolean;
+    has(paths: readonly string[]): boolean;
+    search(query: string, options?: SearchOptions): readonly SearchMatch[];
+    replace(query: string, replacement: string, options?: SearchOptions): ReplaceResult;
+    write(path: string, content: string): void;
+    write(path: string, content: string, range: Range): void;
+    write(files: Readonly<Record<string, string>>): void;
+    prepend(path: string, content: string): void;
+    prepend(files: Readonly<Record<string, string>>): void;
+    append(path: string, content: string): void;
+    append(files: Readonly<Record<string, string>>): void;
+    move(from: string, to: string): boolean;
+    move(mapping: Readonly<Record<string, string>>): boolean;
+    remove(path: string): boolean;
+    remove(paths: readonly string[]): boolean;
+    clear(): void;
+    snapshot(): WorkspaceSnapshot;
+    destroy(): void;
+}
+
+/** An invalid workspace edit or search operation. */
+export declare class WorkspaceError extends Error {
+    readonly code: WorkspaceErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    /**
+     * Create a workspace error.
+     *
+     * @param code - The machine-readable failure code
+     * @param message - The human-readable failure message
+     * @param context - Optional values associated with the failed operation
+     */
+    constructor(code: WorkspaceErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/** The machine-readable failure codes raised by the workspace edit surface. */
+export declare type WorkspaceErrorCode = 'MODALITY' | 'PATTERN' | 'RANGE';
+
+/** Events emitted after workspace mutations complete. */
+export declare type WorkspaceEventMap = {
+    readonly write: readonly [file: FileInterface];
+    readonly remove: readonly [path: string];
+    readonly move: readonly [from: string, to: string];
+    readonly clear: readonly [];
+};
+
+/** A mutable path-keyed editing surface over immutable file values. */
+export declare interface WorkspaceInterface {
+    readonly id: string;
+    readonly emitter: EmitterInterface<WorkspaceEventMap>;
+    readonly count: number;
+    file(path: string): FileInterface | undefined;
+    files(): readonly FileInterface[];
+    read(path: string): string | undefined;
+    read(path: string, range: Range): ReadResult | undefined;
+    read(paths: readonly string[]): Readonly<Record<string, string>>;
+    has(path: string): boolean;
+    has(paths: readonly string[]): boolean;
+    search(query: string, options?: SearchOptions): readonly SearchMatch[];
+    replace(query: string, replacement: string, options?: SearchOptions): ReplaceResult;
+    write(path: string, content: string): void;
+    write(path: string, content: string, range: Range): void;
+    write(files: Readonly<Record<string, string>>): void;
+    prepend(path: string, content: string): void;
+    prepend(files: Readonly<Record<string, string>>): void;
+    append(path: string, content: string): void;
+    append(files: Readonly<Record<string, string>>): void;
+    move(from: string, to: string): boolean;
+    move(mapping: Readonly<Record<string, string>>): boolean;
+    remove(path: string): boolean;
+    remove(paths: readonly string[]): boolean;
+    clear(): void;
+    snapshot(): WorkspaceSnapshot;
+    destroy(): void;
+}
+
+/**
+ * An insertion-ordered workspace registry with an active selection.
+ *
+ * A supplied store adds lenient snapshot `open` and `save` operations. Event defaults flow into
+ * workspaces created through the registry, while observability remains owned by each workspace.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceManager } from '@orkestrel/workspace'
+ *
+ * const manager = new WorkspaceManager()
+ * const workspace = manager.add({ id: 'scratch' })
+ * manager.active === workspace
+ * ```
+ */
+export declare class WorkspaceManager implements WorkspaceManagerInterface {
+    #private;
+    /**
+     * Create a registry.
+     *
+     * @param options - Default event hooks and optional snapshot store
+     */
+    constructor(options?: WorkspaceManagerOptions);
+    get count(): number;
+    get active(): WorkspaceInterface | undefined;
+    workspace(id: string): WorkspaceInterface | undefined;
+    workspaces(): readonly WorkspaceInterface[];
+    add(options?: WorkspaceOptions): WorkspaceInterface;
+    switch(id: string): WorkspaceInterface | undefined;
+    open(id: string): Promise<WorkspaceInterface | undefined>;
+    save(id: string): Promise<boolean>;
+    remove(id: string): boolean;
+    remove(ids: readonly string[]): boolean;
+    clear(): void;
+}
+
+/** An insertion-ordered workspace registry with an active selection and optional durability. */
+export declare interface WorkspaceManagerInterface {
+    readonly count: number;
+    readonly active: WorkspaceInterface | undefined;
+    workspace(id: string): WorkspaceInterface | undefined;
+    workspaces(): readonly WorkspaceInterface[];
+    add(options?: WorkspaceOptions): WorkspaceInterface;
+    switch(id: string): WorkspaceInterface | undefined;
+    open(id: string): Promise<WorkspaceInterface | undefined>;
+    save(id: string): Promise<boolean>;
+    remove(id: string): boolean;
+    remove(ids: readonly string[]): boolean;
+    clear(): void;
+}
+
+/**
+ * Workspace-manager construction options.
+ *
+ * `on` and `error` become defaults for created workspaces; `store` supplies optional durability.
+ */
+export declare interface WorkspaceManagerOptions {
+    readonly on?: EmitterHooks<WorkspaceEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly store?: WorkspaceStoreInterface;
+}
+
+/**
+ * Workspace construction options.
+ *
+ * @remarks
+ * `id` supplies the registry key, `on` supplies initial event listeners, `error` receives isolated
+ * listener failures, and `seed` hydrates initial immutable files without emitting edits.
+ */
+export declare interface WorkspaceOptions {
+    readonly id?: string;
+    readonly on?: EmitterHooks<WorkspaceEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly seed?: Iterable<FileInterface>;
+}
+
+/** A JSON-serializable workspace snapshot. */
+export declare interface WorkspaceSnapshot {
+    readonly id: string;
+    readonly files: readonly FileInterface[];
+}
+
+/** The database row used to persist one opaque workspace snapshot. */
+export declare interface WorkspaceSnapshotRow {
+    readonly id: string;
+    readonly snapshot: unknown;
+}
+
+/** The asynchronous point-access persistence contract for workspace snapshots. */
+export declare interface WorkspaceStoreInterface {
+    /**
+     * Resolve a snapshot.
+     *
+     * @param id - The workspace identifier
+     * @returns The snapshot, or `undefined` when absent
+     */
+    get(id: string): Promise<WorkspaceSnapshot | undefined>;
+    /**
+     * Insert or replace a snapshot under its own identifier.
+     *
+     * @param snapshot - The snapshot to persist
+     * @returns A promise that resolves when persistence completes
+     */
+    set(snapshot: WorkspaceSnapshot): Promise<void>;
+    /**
+     * Delete a snapshot when present.
+     *
+     * @param id - The workspace identifier
+     * @returns A promise that resolves when deletion completes
+     */
+    delete(id: string): Promise<void>;
+}
+
+export { }