@orkestrel/workspace 0.0.6 → 0.0.8

package/README.md

@@ -1,19 +1,19 @@
 # @orkestrel/workspace
 
-The virtual file workspace for the `@orkestrel` line.
+> The virtual file workspace for the `@orkestrel` line: a path-keyed map of immutable files with
+> an editing surface over it, a registry that holds those maps by id under one active selection,
+> and a snapshot store seam that persists them.
 
-A workspace is a path-keyed map of immutable files with an editing surface over it: write, read,
-search, replace, move, remove. Every edit mints a new file value and puts it back under its path,
-so a file is a value a caller can hold and compare rather than a handle that changes underneath it.
-Around that map sit a registry of named workspaces with one active selection, and pluggable stores
-that persist plain snapshots.
+Reach a file by its path — `write`, `read`, `search`, `replace`, `move`, `remove` — and every edit
+mints a new file value and puts it back, so a file is a value you can hold and compare rather than
+a handle that changes underneath you.
 
 It is not a filesystem. There is no disk, no `node:fs`, no watcher, no synchronization lifecycle,
 and no dirty-state tracking — a path is a key, not a location. Durability is a separate seam: a
 snapshot is a plain serializable value, and a store is the thing that keeps one.
 
 Nothing here is model-specific. An agent loop, a tool handler, and plain application code are all
-just callers.
+callers.
 
 ## Install
 
@@ -41,7 +41,7 @@ Ranged edits clamp to the text they address, search is literal until you ask for
 absent path answers with `undefined` instead of throwing. Give the manager a store and `save` and
 `open` round-trip a workspace through it.
 
-See the [workspace guide](guides/src/workspace.md) for the complete surface, edit semantics,
+See the [workspace guide](guides/workspace.md) for the complete surface, edit semantics,
 events, and stores.
 
 ## Requirements

package/dist/src/core/index.cjs

@@ -4,9 +4,9 @@ let _orkestrel_database = require("@orkestrel/database");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
 /**
-* File extensions mapped to language tags for text content.
+* Maps file extensions to language tags for text content.
 *
-* Unknown extensions intentionally fall back to `text` in
+* The table is frozen, and an extension it does not list falls back to `text` in
 * {@link import('./helpers.js').inferLanguage}.
 */
 var EXTENSION_LANGUAGES = Object.freeze({
@@ -53,12 +53,15 @@ var EXTENSION_LANGUAGES = Object.freeze({
 });
 //#endregion
 //#region src/core/errors.ts
-/** An invalid workspace edit or search operation. */
+/**
+* Reports an invalid workspace edit or search operation, carrying a {@link WorkspaceErrorCode}
+* and, when the operation had one, the context it ran under.
+*/
 var WorkspaceError = class extends Error {
 	code;
 	context;
 	/**
-	* Create a workspace error.
+	* Creates a workspace error.
 	*
 	* @param code - The machine-readable failure code
 	* @param message - The human-readable failure message
@@ -72,10 +75,14 @@ var WorkspaceError = class extends Error {
 	}
 };
 /**
-* Narrow a caught value to a {@link WorkspaceError}.
+* Narrows a caught value to a {@link WorkspaceError}.
+*
+* @remarks
+* The check is one `instanceof` test, so it stays total: every input answers `true` or `false`
+* and none throws.
 *
 * @param value - The caught value
-* @returns Whether the value is a workspace error
+* @returns True if the value is a workspace error; false otherwise
 *
 * @example
 * ```ts
@@ -88,7 +95,7 @@ function isWorkspaceError(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Infer a language tag from the final file extension.
+* Infers 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
@@ -104,10 +111,10 @@ function inferLanguage(path) {
 	return EXTENSION_LANGUAGES[path.slice(dot + 1).toLowerCase()] ?? "text";
 }
 /**
-* Determine whether content is the text arm.
+* Determines whether content is the text arm.
 *
 * @param content - The file content
-* @returns Whether the content carries text and a language
+* @returns True if the content carries text and a language; false otherwise
 *
 * @example
 * ```ts
@@ -118,57 +125,21 @@ function isText(content) {
 	return "text" in content;
 }
 /**
-* Determine whether content is the binary arm.
+* Determines whether content is the binary arm.
 *
 * @param content - The file content
-* @returns Whether the content carries base64 data and a MIME
+* @returns True if the content carries a base64 string and a MIME; false otherwise
 *
 * @example
 * ```ts
-* isBinary({ data: 'AAAA', mime: 'image/png' }) // true
+* isBinary({ base64: 'AAAA', mime: 'image/png' }) // true
 * ```
 */
 function isBinary(content) {
-	return "data" in content;
-}
-/**
-* 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 })
-* ```
-*/
-function isFile(value) {
-	return (0, _orkestrel_contract.holds)(() => {
-		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-		if (!(0, _orkestrel_contract.isString)(value.path) || !(0, _orkestrel_contract.literalOf)("created", "modified")(value.state)) return false;
-		if (!(0, _orkestrel_contract.isNumber)(value.size) || !(0, _orkestrel_contract.isNumber)(value.lines)) return false;
-		if (!(0, _orkestrel_contract.isRecord)(value.content)) return false;
-		const text = (0, _orkestrel_contract.isString)(value.content.text) && (0, _orkestrel_contract.isString)(value.content.language);
-		const binary = (0, _orkestrel_contract.isString)(value.content.data) && (0, _orkestrel_contract.literalOf)("image/png", "image/jpeg", "image/gif", "image/webp")(value.content.mime);
-		return text || binary;
-	});
-}
-/**
-* 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
-* ```
-*/
-function isWorkspaceSnapshot(value) {
-	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && (0, _orkestrel_contract.isString)(value.id) && (0, _orkestrel_contract.arrayOf)(isFile)(value.files));
+	return "base64" in content;
 }
 /**
-* Compute the byte size of file content.
+* Computes the byte size of file content.
 *
 * @param content - The content to measure
 * @returns UTF-8 bytes for text or decoded bytes for binary content
@@ -180,10 +151,10 @@ function isWorkspaceSnapshot(value) {
 */
 function computeSize(content) {
 	if (isText(content)) return new TextEncoder().encode(content.text).length;
-	return decodedSize(content.data);
+	return computeDecodedSize(content.base64);
 }
 /**
-* Count the lines in file content.
+* Counts the lines in file content.
 *
 * @param content - The content to inspect
 * @returns The text line count, or zero for empty text and binary content
@@ -201,27 +172,27 @@ function countLines(content) {
 	return count;
 }
 /**
-* Compute the decoded byte length of a base64 string.
+* Computes the decoded byte length of a base64 string, arithmetically rather than by decoding it.
 *
-* @param base64 - The base64 data
+* @param base64 - The base64 string
 * @returns The decoded byte count
 *
 * @example
 * ```ts
-* decodedSize('AAAA') // 3
+* computeDecodedSize('AAAA') // 3
 * ```
 */
-function decodedSize(base64) {
+function computeDecodedSize(base64) {
 	let padding = 0;
 	if (base64.endsWith("==")) padding = 2;
 	else if (base64.endsWith("=")) padding = 1;
 	return Math.floor(base64.length * 3 / 4) - padding;
 }
 /**
-* Determine whether a 1-based range is structurally valid.
+* Determines whether a 1-based range is structurally valid.
 *
 * @param range - The range to inspect
-* @returns Whether both positions are positive and ordered
+* @returns True if both positions are positive and ordered; false otherwise
 *
 * @example
 * ```ts
@@ -235,7 +206,7 @@ function isValidRange(range) {
 	return !(range.start.line === range.end.line && range.start.column > range.end.column);
 }
 /**
-* Clamp a position to text bounds.
+* Clamps a position to text bounds.
 *
 * @param text - The addressed text
 * @param position - The requested position
@@ -256,7 +227,7 @@ function clampPosition(text, position) {
 	};
 }
 /**
-* Clamp both positions in a range to text bounds.
+* Clamps both positions in a range to text bounds.
 *
 * @param text - The addressed text
 * @param range - The requested range
@@ -274,7 +245,7 @@ function clampRange(text, range) {
 	};
 }
 /**
-* Convert a 1-based position to a zero-based string offset.
+* Converts a 1-based position to a zero-based string offset.
 *
 * @param text - The addressed text
 * @param position - The requested position
@@ -293,7 +264,7 @@ function offsetAt(text, position) {
 	return Math.min(offset, text.length);
 }
 /**
-* Slice a clamped half-open text range.
+* Slices a clamped half-open text range.
 *
 * @param text - The source text
 * @param range - The requested range
@@ -309,7 +280,7 @@ function sliceRange(text, range) {
 	return text.slice(offsetAt(text, clamped.start), offsetAt(text, clamped.end));
 }
 /**
-* Replace a clamped half-open text range.
+* Replaces a clamped half-open text range.
 *
 * @param text - The source text
 * @param range - The requested range
@@ -328,7 +299,7 @@ function spliceRange(text, range, replacement) {
 	return text.slice(0, start) + replacement + text.slice(end);
 }
 /**
-* Assemble a nested range from four 1-based coordinates.
+* Assembles a nested range from four 1-based coordinates.
 *
 * @param fromLine - The start line
 * @param fromColumn - The start column
@@ -354,7 +325,7 @@ function rangeOf(fromLine, fromColumn, toLine, toColumn) {
 	};
 }
 /**
-* Escape regular-expression metacharacters for literal matching.
+* Escapes regular-expression metacharacters for literal matching.
 *
 * @param value - The literal text
 * @returns The escaped regular-expression source
@@ -368,13 +339,52 @@ function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
+//#region src/core/validators.ts
+/**
+* Narrows an unknown value to an immutable file record.
+*
+* @param value - The value to inspect
+* @returns True if the value has the file shape; false otherwise
+*
+* @example
+* ```ts
+* isFile({ path: 'a.txt', content: { text: 'a', language: 'text' }, state: 'created', size: 1, lines: 1 })
+* ```
+*/
+function isFile(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		if (!(0, _orkestrel_contract.isString)(value.path) || !(0, _orkestrel_contract.literalOf)("created", "modified")(value.state)) return false;
+		if (!(0, _orkestrel_contract.isNumber)(value.size) || !(0, _orkestrel_contract.isNumber)(value.lines)) return false;
+		if (!(0, _orkestrel_contract.isRecord)(value.content)) return false;
+		const text = (0, _orkestrel_contract.isString)(value.content.text) && (0, _orkestrel_contract.isString)(value.content.language);
+		const binary = (0, _orkestrel_contract.isString)(value.content.base64) && (0, _orkestrel_contract.literalOf)("image/png", "image/jpeg", "image/gif", "image/webp")(value.content.mime);
+		return text || binary;
+	});
+}
+/**
+* Narrows an unknown value to a workspace snapshot.
+*
+* @param value - The value read from a persistence boundary
+* @returns True if the value has the workspace snapshot shape; false otherwise
+*
+* @example
+* ```ts
+* isWorkspaceSnapshot({ id: 'work', files: [] }) // true
+* ```
+*/
+function isWorkspaceSnapshot(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && (0, _orkestrel_contract.isString)(value.id) && (0, _orkestrel_contract.arrayOf)(isFile)(value.files));
+}
+//#endregion
 //#region src/core/workspaces/Workspace.ts
 /**
-* A mutable path-keyed editing surface over immutable files.
+* Implements `WorkspaceInterface` over one insertion-ordered path map the instance owns,
+* projecting fresh arrays on every read.
 *
 * 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.
+* file map has changed.
 *
 * @example
 * ```ts
@@ -391,7 +401,7 @@ var Workspace = class {
 	#files = /* @__PURE__ */ new Map();
 	#emitter;
 	/**
-	* Create a workspace.
+	* Creates a workspace.
 	*
 	* @param options - Optional identity, emitter configuration, and initial files
 	*/
@@ -437,7 +447,7 @@ var Workspace = class {
 		};
 	}
 	has(path) {
-		if ((0, _orkestrel_contract.isArray)(path)) return path.some((one) => this.#files.has(one));
+		if ((0, _orkestrel_contract.isArray)(path)) return path.every((one) => this.#files.has(one));
 		return this.#files.has(path);
 	}
 	search(query, options) {
@@ -447,7 +457,7 @@ var Workspace = class {
 		for (const file of this.#files.values()) {
 			if (limit !== void 0 && matches.length >= limit) break;
 			if (!isText(file.content)) continue;
-			const lines = file.content.text.split("\n");
+			const lines = file.content.text.split(/\r\n|\n/);
 			for (let index = 0; index < lines.length; index += 1) {
 				if (limit !== void 0 && matches.length >= limit) break;
 				const lineText = lines[index] ?? "";
@@ -501,39 +511,42 @@ var Workspace = class {
 			for (const [one, text] of Object.entries(path)) this.#write(one, text);
 			return;
 		}
-		const text = content ?? "";
+		if (content === void 0) return;
 		if (!range) {
-			this.#write(path, text);
+			this.#write(path, content);
 			return;
 		}
-		this.#splice(path, text, range);
+		this.#splice(path, content, range);
 	}
 	prepend(path, content) {
 		if ((0, _orkestrel_contract.isRecord)(path)) {
 			for (const [one, text] of Object.entries(path)) this.#prepend(one, text);
 			return;
 		}
-		this.#prepend(path, content ?? "");
+		if (content === void 0) return;
+		this.#prepend(path, content);
 	}
 	append(path, content) {
 		if ((0, _orkestrel_contract.isRecord)(path)) {
 			for (const [one, text] of Object.entries(path)) this.#append(one, text);
 			return;
 		}
-		this.#append(path, content ?? "");
+		if (content === void 0) return;
+		this.#append(path, content);
 	}
 	move(from, to) {
 		if ((0, _orkestrel_contract.isRecord)(from)) {
-			let moved = false;
-			for (const [one, target] of Object.entries(from)) if (this.#move(one, target)) moved = true;
+			let moved = true;
+			for (const [one, target] of Object.entries(from)) if (!this.#move(one, target)) moved = false;
 			return moved;
 		}
-		return this.#move(from, to ?? "");
+		if (to === void 0) return false;
+		return this.#move(from, to);
 	}
 	remove(path) {
 		if ((0, _orkestrel_contract.isArray)(path)) {
-			let removed = false;
-			for (const one of path) if (this.#remove(one)) removed = true;
+			let removed = true;
+			for (const one of path) if (!this.#remove(one)) removed = false;
 			return removed;
 		}
 		return this.#remove(path);
@@ -566,7 +579,7 @@ var Workspace = class {
 	}
 	#splice(path, content, range) {
 		const existing = this.#files.get(path);
-		if (!existing) throw new WorkspaceError("MODALITY", `Cannot splice a range of a missing file: ${path}`, { path });
+		if (!existing) throw new WorkspaceError("MISSING", `Cannot splice a range of a missing file: ${path}`, { path });
 		if (!isText(existing.content)) throw new WorkspaceError("MODALITY", `Cannot splice a range of a binary file: ${path}`, { path });
 		if (!isValidRange(range)) throw new WorkspaceError("RANGE", `Invalid range for file: ${path}`, {
 			path,
@@ -635,7 +648,8 @@ var Workspace = class {
 //#endregion
 //#region src/core/workspaces/WorkspaceManager.ts
 /**
-* An insertion-ordered workspace registry with an active selection.
+* Implements `WorkspaceManagerInterface` over an insertion-ordered id map and one active id
+* the instance owns, resolving `active` through that map on every read and holding no emitter.
 *
 * 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.
@@ -656,7 +670,7 @@ var WorkspaceManager = class {
 	#error;
 	#store;
 	/**
-	* Create a registry.
+	* Creates a registry.
 	*
 	* @param options - Default event hooks and optional snapshot store
 	*/
@@ -720,8 +734,8 @@ var WorkspaceManager = class {
 	}
 	remove(ids) {
 		if ((0, _orkestrel_contract.isArray)(ids)) {
-			let removed = false;
-			for (const id of ids) if (this.#drop(id)) removed = true;
+			let removed = true;
+			for (const id of ids) if (!this.#drop(id)) removed = false;
 			return removed;
 		}
 		return this.#drop(ids);
@@ -743,21 +757,27 @@ var WorkspaceManager = class {
 //#endregion
 //#region src/core/workspaces/stores/DatabaseWorkspaceStore.ts
 /**
-* A workspace snapshot store over a database table.
+* Persists workspace snapshots in 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()
+* import { rawShape, stringShape } from '@orkestrel/contract'
+* import { createDatabase, createMemoryDriver } from '@orkestrel/database'
+* import { DatabaseWorkspaceStore } from '@orkestrel/workspace'
+*
+* const database = createDatabase({
+* 	driver: createMemoryDriver(),
+* 	tables: { workspaces: { id: stringShape(), snapshot: rawShape({}) } },
+* })
+* const store = new DatabaseWorkspaceStore(database.table('workspaces'))
 * ```
 */
 var DatabaseWorkspaceStore = class {
 	#table;
 	/**
-	* Wrap a workspace snapshot table.
+	* Wraps a workspace snapshot table.
 	*
 	* @param table - The table keyed by workspace identifier
 	*/
@@ -782,7 +802,7 @@ var DatabaseWorkspaceStore = class {
 //#endregion
 //#region src/core/workspaces/stores/MemoryWorkspaceStore.ts
 /**
-* A process-local workspace snapshot store.
+* Holds workspace snapshots in the current process.
 *
 * @example
 * ```ts
@@ -808,16 +828,37 @@ var MemoryWorkspaceStore = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create an immutable file with derived size and line counts.
+* Creates an immutable file with derived size and line counts.
 *
 * @param input - The file path, content, and optional state
 * @returns A frozen file record
 *
-* @example
+* @example Files and content
 * ```ts
-* import { createFile, createTextContent } from '@orkestrel/workspace'
-*
-* createFile({ path: 'a.txt', content: createTextContent('hello', 'text') })
+* import {
+* 	computeSize,
+* 	countLines,
+* 	createBinaryContent,
+* 	createFile,
+* 	createTextContent,
+* 	inferLanguage,
+* 	isBinary,
+* 	isText,
+* } from '@orkestrel/workspace'
+*
+* const note = createFile({
+* 	path: 'notes.md',
+* 	content: createTextContent('# Title\nBody', inferLanguage('notes.md')), // 'markdown'
+* })
+*
+* note.size // 12 — UTF-8 bytes, through computeSize
+* note.lines // 2 — through countLines
+* note.state // 'created'
+* isText(note.content) // true
+*
+* const icon = createFile({ path: 'icon.png', content: createBinaryContent('AAAA', 'image/png') })
+* isBinary(icon.content) // true
+* icon.size // 3 — decoded base64 bytes, through computeDecodedSize
 * ```
 */
 function createFile(input) {
@@ -830,7 +871,8 @@ function createFile(input) {
 	});
 }
 /**
-* Create the text arm of {@link FileContent}.
+* Creates the text arm of {@link FileContent}, returned as {@link TextContent} rather than as
+* the whole union.
 *
 * @param text - The text body
 * @param language - The language tag
@@ -850,9 +892,10 @@ function createTextContent(text, language) {
 	};
 }
 /**
-* Create the binary arm of {@link FileContent}.
+* Creates the binary arm of {@link FileContent}, returned as {@link BinaryContent} rather than
+* as the whole union.
 *
-* @param data - The base64 payload
+* @param base64 - The base64 payload
 * @param mime - The binary MIME
 * @returns Binary file content
 *
@@ -863,14 +906,14 @@ function createTextContent(text, language) {
 * createBinaryContent('AAAA', 'image/png')
 * ```
 */
-function createBinaryContent(data, mime) {
+function createBinaryContent(base64, mime) {
 	return {
-		data,
+		base64,
 		mime
 	};
 }
 /**
-* Create a workspace.
+* Creates a workspace with the same identity, emitter, and seed options the constructor takes.
 *
 * @param options - Optional identity, emitter configuration, and initial files
 * @returns A working workspace
@@ -887,7 +930,7 @@ function createWorkspace(options) {
 	return new Workspace(options);
 }
 /**
-* Create an in-memory workspace snapshot store.
+* Creates an in-memory workspace snapshot store.
 *
 * @returns A process-local workspace store
 *
@@ -902,9 +945,10 @@ function createMemoryWorkspaceStore() {
 	return new MemoryWorkspaceStore();
 }
 /**
-* Create a database-backed workspace snapshot store.
+* Creates a database-backed workspace snapshot store, over an in-memory driver when the caller
+* supplies none.
 *
-* @param driver - The database driver; defaults to an in-memory driver
+* @param driver - The database driver. Default: an in-memory driver.
 * @returns A workspace store backed by the supplied driver
 *
 * @example
@@ -925,7 +969,7 @@ function createDatabaseWorkspaceStore(driver = (0, _orkestrel_database.createMem
 	}).table("workspaces"));
 }
 /**
-* Create an empty workspace registry.
+* Creates an empty workspace registry.
 *
 * @param options - Default event hooks and optional durability
 * @returns A workspace manager
@@ -950,6 +994,7 @@ exports.WorkspaceError = WorkspaceError;
 exports.WorkspaceManager = WorkspaceManager;
 exports.clampPosition = clampPosition;
 exports.clampRange = clampRange;
+exports.computeDecodedSize = computeDecodedSize;
 exports.computeSize = computeSize;
 exports.countLines = countLines;
 exports.createBinaryContent = createBinaryContent;
@@ -959,7 +1004,6 @@ exports.createMemoryWorkspaceStore = createMemoryWorkspaceStore;
 exports.createTextContent = createTextContent;
 exports.createWorkspace = createWorkspace;
 exports.createWorkspaceManager = createWorkspaceManager;
-exports.decodedSize = decodedSize;
 exports.escapeRegExp = escapeRegExp;
 exports.inferLanguage = inferLanguage;
 exports.isBinary = isBinary;