@orkestrel/workspace 0.0.6 → 0.0.8

package/dist/src/core/index.js

@@ -3,9 +3,9 @@ import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { Emitter } from "@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({
@@ -52,12 +52,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
@@ -71,10 +74,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
@@ -87,7 +94,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
@@ -103,10 +110,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
@@ -117,57 +124,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 holds(() => {
-		if (!isRecord(value)) return false;
-		if (!isString(value.path) || !literalOf("created", "modified")(value.state)) return false;
-		if (!isNumber(value.size) || !isNumber(value.lines)) return false;
-		if (!isRecord(value.content)) return false;
-		const text = isString(value.content.text) && isString(value.content.language);
-		const binary = isString(value.content.data) && 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 holds(() => isRecord(value) && isString(value.id) && 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
@@ -179,10 +150,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
@@ -200,27 +171,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
@@ -234,7 +205,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
@@ -255,7 +226,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
@@ -273,7 +244,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
@@ -292,7 +263,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
@@ -308,7 +279,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
@@ -327,7 +298,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
@@ -353,7 +324,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
@@ -367,13 +338,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 holds(() => {
+		if (!isRecord(value)) return false;
+		if (!isString(value.path) || !literalOf("created", "modified")(value.state)) return false;
+		if (!isNumber(value.size) || !isNumber(value.lines)) return false;
+		if (!isRecord(value.content)) return false;
+		const text = isString(value.content.text) && isString(value.content.language);
+		const binary = isString(value.content.base64) && 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 holds(() => isRecord(value) && isString(value.id) && 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
@@ -390,7 +400,7 @@ var Workspace = class {
 	#files = /* @__PURE__ */ new Map();
 	#emitter;
 	/**
-	* Create a workspace.
+	* Creates a workspace.
 	*
 	* @param options - Optional identity, emitter configuration, and initial files
 	*/
@@ -436,7 +446,7 @@ var Workspace = class {
 		};
 	}
 	has(path) {
-		if (isArray(path)) return path.some((one) => this.#files.has(one));
+		if (isArray(path)) return path.every((one) => this.#files.has(one));
 		return this.#files.has(path);
 	}
 	search(query, options) {
@@ -446,7 +456,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] ?? "";
@@ -500,39 +510,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 (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 (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 (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 (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);
@@ -565,7 +578,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,
@@ -634,7 +647,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.
@@ -655,7 +669,7 @@ var WorkspaceManager = class {
 	#error;
 	#store;
 	/**
-	* Create a registry.
+	* Creates a registry.
 	*
 	* @param options - Default event hooks and optional snapshot store
 	*/
@@ -719,8 +733,8 @@ var WorkspaceManager = class {
 	}
 	remove(ids) {
 		if (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);
@@ -742,21 +756,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
 	*/
@@ -781,7 +801,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
@@ -807,16 +827,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) {
@@ -829,7 +870,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
@@ -849,9 +891,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
 *
@@ -862,14 +905,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
@@ -886,7 +929,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
 *
@@ -901,9 +944,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
@@ -924,7 +968,7 @@ function createDatabaseWorkspaceStore(driver = createMemoryDriver()) {
 	}).table("workspaces"));
 }
 /**
-* Create an empty workspace registry.
+* Creates an empty workspace registry.
 *
 * @param options - Default event hooks and optional durability
 * @returns A workspace manager
@@ -941,6 +985,6 @@ function createWorkspaceManager(options) {
 	return new WorkspaceManager(options);
 }
 //#endregion
-export { DatabaseWorkspaceStore, EXTENSION_LANGUAGES, MemoryWorkspaceStore, Workspace, WorkspaceError, WorkspaceManager, clampPosition, clampRange, computeSize, countLines, createBinaryContent, createDatabaseWorkspaceStore, createFile, createMemoryWorkspaceStore, createTextContent, createWorkspace, createWorkspaceManager, decodedSize, escapeRegExp, inferLanguage, isBinary, isFile, isText, isValidRange, isWorkspaceError, isWorkspaceSnapshot, offsetAt, rangeOf, sliceRange, spliceRange };
+export { DatabaseWorkspaceStore, EXTENSION_LANGUAGES, MemoryWorkspaceStore, Workspace, WorkspaceError, WorkspaceManager, clampPosition, clampRange, computeDecodedSize, computeSize, countLines, createBinaryContent, createDatabaseWorkspaceStore, createFile, createMemoryWorkspaceStore, createTextContent, createWorkspace, createWorkspaceManager, escapeRegExp, inferLanguage, isBinary, isFile, isText, isValidRange, isWorkspaceError, isWorkspaceSnapshot, offsetAt, rangeOf, sliceRange, spliceRange };
 
 //# sourceMappingURL=index.js.map