@decohere/core 0.0.1-dev.125 → 0.0.1-dev.5

package/src/interop/yarn/yarn.ts

@@ -0,0 +1,28 @@
+import { Shell } from "../shell/shell.js";
+import type { PackageManager } from "../types/package-manager.js";
+import type { YarnOptions } from "./yarn.types.js";
+
+const Commands = {
+	install: "install",
+};
+
+export class Yarn extends Shell implements PackageManager {
+	public readonly name = "yarn" as const;
+	protected program: string = "yarn";
+
+	public async install(options: YarnOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run({ cwd }, Commands.install);
+	}
+
+	public async syncLockFile(options: YarnOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run(
+			{ cwd },
+			Commands.install,
+			"--mode",
+			"update-lockfile",
+			"--ignore-scripts",
+		);
+	}
+}

package/src/interop/yarn/yarn.types.ts

@@ -0,0 +1,3 @@
+export type YarnOptions = {
+	cwd?: string;
+};

package/src/io/copy-file.ts

@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export type CopyFileOptions = {
+	mkdir?: boolean;
+};
+
+export async function copyFile(src: string, dest: string, options: CopyFileOptions = {}) {
+	if (options.mkdir) {
+		await fs.mkdir(path.dirname(dest), { recursive: true });
+	}
+	await fs.copyFile(src, dest);
+}

package/src/io/delete-file.ts

@@ -0,0 +1,4 @@
+import fs from "node:fs/promises";
+export async function deleteFile(filePath: string) {
+	return fs.rm(filePath, { force: true });
+}

package/src/io/directory-exists.ts

@@ -0,0 +1,9 @@
+import fs from "node:fs/promises";
+export async function directoryExists(path: string): Promise<boolean> {
+	try {
+		await fs.access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/io/file-exists.ts

@@ -0,0 +1,10 @@
+import { stat } from "node:fs/promises";
+
+export async function fileExists(path: string): Promise<boolean> {
+	try {
+		const stats = await stat(path);
+		return stats.isFile();
+	} catch {
+		return false;
+	}
+}

package/src/io/find-directories.ts

@@ -0,0 +1,13 @@
+import { glob } from "glob";
+import type { Directory } from "./types/directory.type.js";
+
+export async function findDirectories(...pattern: string[]): Promise<Directory[]> {
+	const paths = await glob(pattern, { withFileTypes: true });
+	const dirs = paths
+		.filter((p) => p.isDirectory())
+		.map((p) => ({
+			name: p.name,
+			parentPath: p.parentPath,
+		}));
+	return dirs;
+}

package/src/io/find-file.ts

@@ -0,0 +1,37 @@
+import { glob } from "glob";
+import { FileEx } from "./types/file.js";
+
+export type FindFileOptions = {
+	cwd: string;
+	ignore?: string | string[];
+};
+
+export async function findFile(pattern: string) {
+	const files = await glob(pattern, { includeChildMatches: false });
+	if (files.length === 0) {
+		return;
+	}
+	const file = {
+		relativePath: files.at(0),
+	};
+	return file;
+}
+
+export async function findFiles(
+	patterns: string[],
+	options?: FindFileOptions,
+): Promise<FileEx[]> {
+	const paths = await glob(patterns, {
+		...options,
+		withFileTypes: true,
+	});
+	const files = paths
+		.filter((p) => p.isFile())
+		.map((p) => {
+			return new FileEx({
+				relativePath: p.relative(),
+				fullPath: p.fullpath(),
+			});
+		});
+	return files;
+}

package/{es6/src/io/io.js → src/io/io.ts}

@@ -2,7 +2,10 @@ export * from "./copy-file.js";
 export * from "./delete-file.js";
 export * from "./directory-exists.js";
 export * from "./file-exists.js";
+export * from "./find-directories.js";
+export * from "./find-file.js";
 export * from "./read-file.js";
 export * from "./remove-dir.js";
 export * from "./url-to-path.js";
+export * from "./watch.js";
 export * from "./write-file.js";

package/src/io/read-file.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+import type { File } from "./types/file.js";
+export async function readFiles(
+	filePaths: File[],
+	encoding: BufferEncoding = "utf8",
+): Promise<string[]> {
+	const data = await Promise.all(filePaths.map((file) => readFile(file.fullPath, encoding)));
+	return data;
+}
+
+export async function readFile(
+	filePath: string,
+	encoding: BufferEncoding = "utf8",
+): Promise<string> {
+	const data = await fs.readFile(filePath, encoding);
+	return data;
+}
+
+export async function readJsonFile<T>(
+	filePath: string,
+	encoding: BufferEncoding = "utf8",
+): Promise<T> {
+	const data = await readFile(filePath, encoding);
+	return JSON.parse(data);
+}

package/src/io/remove-dir.ts

@@ -0,0 +1,11 @@
+import fs from "node:fs/promises";
+export type RemoveDirOptions = {
+	force: boolean;
+	recursive: boolean;
+};
+export async function removeDir(
+	path: string,
+	options: RemoveDirOptions = { recursive: false, force: false },
+) {
+	await fs.rm(path, options);
+}

package/src/io/types/directory.type.ts

@@ -0,0 +1,4 @@
+export type Directory = {
+	name: string;
+	parentPath: string;
+};

package/src/io/types/file.ts

@@ -0,0 +1,34 @@
+import { readFile } from "../read-file.js";
+
+export type File = {
+	fullPath: string;
+	relativePath: string;
+};
+
+export class FileEx implements File {
+	public constructor(data: Partial<File> & { content?: string }) {
+		this.fullPath = data.fullPath;
+		this.relativePath = data.relativePath ?? data.fullPath;
+		this.#content = data.content;
+	}
+	#content?: string;
+	public fullPath: string;
+	public relativePath: string;
+	public toString() {
+		return this.relativePath;
+	}
+	public async getContent() {
+		if (this.#content != null) return this.#content;
+		return readFile(this.fullPath);
+	}
+}
+
+export type Watcher = {
+	readonly ready: Promise<void>;
+	on(event: "ready", handler: () => unknown): Watcher;
+	on(
+		event: "add" | "change" | "addDir" | "unlink" | "unlinkDir",
+		handler: (file: File) => unknown,
+	): Watcher;
+	close(): void;
+};

package/src/io/url-to-path.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const fileUrlToPath = (url: string) => {
+	try {
+		return fileURLToPath(url);
+	} catch {
+		return url;
+	}
+};
+
+export const pathToFileUrl = (path: string) => {
+	try {
+		return pathToFileURL(path).toString();
+	} catch {
+		return path;
+	}
+};

package/src/io/watch.ts

@@ -0,0 +1,290 @@
+import { type FSWatcher, watch as nativeWatch, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import picomatch from "picomatch";
+import { type File, FileEx, type Watcher } from "./types/file.js";
+
+export type WatchOptions = {
+	include?: string[];
+	ignore?: string[];
+	cwd?: string;
+	ignoreInitial?: boolean;
+};
+
+export type WatchEventName = "add" | "change" | "addDir" | "unlink" | "unlinkDir";
+export const WatchEvents = {
+	add: "add",
+	change: "change",
+	addDir: "addDir",
+	unlink: "unlink",
+	unlinkDir: "unlinkDir",
+} satisfies Record<string, WatchEventName>;
+export function watch(directory: string, options: WatchOptions = { cwd: "." }) {
+	const { include, ignore, ignoreInitial = false } = options;
+
+	const changeCoalesceMs = 25;
+
+	const handlers = {
+		ready: new Set<() => unknown>(),
+		add: new Set<(file: File) => unknown>(),
+		change: new Set<(file: File) => unknown>(),
+		addDir: new Set<(file: File) => unknown>(),
+		unlink: new Set<(file: File) => unknown>(),
+		unlinkDir: new Set<(file: File) => unknown>(),
+	};
+
+	let resolveReady: (() => void) | undefined;
+	const ready = new Promise<void>((resolve) => {
+		resolveReady = resolve;
+	});
+
+	const snapshot = buildSnapshot(directory);
+
+	const isFiltered = (relativePath: string) => {
+		const posixRelativePath = toPosixPath(relativePath);
+		const posixFullPath = toPosixPath(path.resolve(directory, relativePath));
+		const matchesEitherPath = (patterns: string[]) =>
+			picomatch.isMatch(posixRelativePath, patterns) ||
+			picomatch.isMatch(posixFullPath, patterns);
+
+		if (include && include.length > 0) {
+			return !matchesEitherPath(include);
+		}
+
+		if (ignore && ignore.length > 0) {
+			return matchesEitherPath(ignore);
+		}
+
+		return false;
+	};
+
+	const emit = (event: WatchEventName, relativePath: string) => {
+		if (isFiltered(relativePath)) {
+			return;
+		}
+
+		const fullPath = path.resolve(directory, relativePath);
+		for (const handler of handlers[event]) {
+			handler(new FileEx({ fullPath, relativePath }));
+		}
+	};
+
+	const pendingChangeTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+	const emitChange = (relativePath: string) => {
+		const existing = pendingChangeTimers.get(relativePath);
+		if (existing != null) {
+			clearTimeout(existing);
+		}
+
+		const timer = setTimeout(() => {
+			pendingChangeTimers.delete(relativePath);
+			emit("change", relativePath);
+		}, changeCoalesceMs);
+
+		pendingChangeTimers.set(relativePath, timer);
+	};
+
+	const emitReady = () => {
+		for (const handler of handlers.ready) {
+			handler();
+		}
+	};
+
+	queueMicrotask(() => {
+		if (!ignoreInitial) {
+			for (const [relativePath, entry] of snapshot) {
+				emit(entry.isDirectory ? "addDir" : "add", relativePath);
+			}
+		}
+
+		emitReady();
+		resolveReady?.();
+		resolveReady = undefined;
+	});
+
+	// One non-recursive watcher per directory. Node's recursive mode on Linux tracks files
+	// individually and goes silent for a file once an editor replaces it with an atomic save
+	// (write temp file, rename over the original); directory watchers keep seeing it (#505).
+	const directoryWatchers = new Map<string, FSWatcher>();
+
+	const watchDirectory = (relativeDir: string) => {
+		if (directoryWatchers.has(relativeDir)) {
+			return;
+		}
+		try {
+			const watcher = nativeWatch(
+				path.resolve(directory, relativeDir),
+				(_eventType, fileName) => {
+					if (fileName != null) {
+						onFsEvent(path.posix.join(relativeDir, toPosixPath(fileName.toString())));
+					}
+				},
+			);
+			watcher.on("error", () => unwatchDirectory(relativeDir));
+			directoryWatchers.set(relativeDir, watcher);
+		} catch {
+			// The directory vanished before we could watch it; its unlink event covers it.
+		}
+	};
+
+	const unwatchDirectory = (relativeDir: string) => {
+		for (const [watchedDir, watcher] of directoryWatchers) {
+			if (watchedDir === relativeDir || watchedDir.startsWith(`${relativeDir}/`)) {
+				watcher.close();
+				directoryWatchers.delete(watchedDir);
+			}
+		}
+	};
+
+	/** A directory appeared: watch it, and report what was created in it before we were watching. */
+	const addDirectory = (relativeDir: string) => {
+		watchDirectory(relativeDir);
+		const found = new Map<string, { isDirectory: boolean; fingerprint: string }>();
+		try {
+			collectSnapshotEntries(directory, path.resolve(directory, relativeDir), found);
+		} catch {
+			return;
+		}
+		for (const [relativePath, entry] of found) {
+			if (snapshot.has(relativePath)) continue;
+			snapshot.set(relativePath, entry);
+			if (entry.isDirectory) watchDirectory(relativePath);
+			emit(entry.isDirectory ? "addDir" : "add", relativePath);
+		}
+	};
+
+	/** A directory went away: stop watching it and forget everything that was under it. */
+	const removeDirectoryContents = (relativeDir: string) => {
+		unwatchDirectory(relativeDir);
+		// oxlint-disable-next-line unicorn/no-useless-spread -- iterate a copy: the loop deletes from the snapshot
+		for (const [relativePath, entry] of [...snapshot]) {
+			if (relativePath.startsWith(`${relativeDir}/`)) {
+				snapshot.delete(relativePath);
+				emit(entry.isDirectory ? "unlinkDir" : "unlink", relativePath);
+			}
+		}
+	};
+
+	const onFsEvent = (eventPath: string) => {
+		const relativePath = eventPath === "." ? "" : eventPath;
+		if (relativePath.length === 0) {
+			return;
+		}
+
+		const fullPath = path.resolve(directory, relativePath);
+		const previous = snapshot.get(relativePath);
+
+		try {
+			const stat = statSync(fullPath);
+			const current = toSnapshotEntry(stat);
+			snapshot.set(relativePath, current);
+
+			if (previous == null) {
+				emit(current.isDirectory ? "addDir" : "add", relativePath);
+				if (current.isDirectory) addDirectory(relativePath);
+				return;
+			}
+
+			if (previous.isDirectory !== current.isDirectory) {
+				if (previous.isDirectory) removeDirectoryContents(relativePath);
+				emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+				emit(current.isDirectory ? "addDir" : "add", relativePath);
+				return;
+			}
+
+			if (!current.isDirectory && previous.fingerprint !== current.fingerprint) {
+				emitChange(relativePath);
+			}
+		} catch {
+			if (previous == null) {
+				return;
+			}
+
+			snapshot.delete(relativePath);
+			const pending = pendingChangeTimers.get(relativePath);
+			if (pending != null) {
+				clearTimeout(pending);
+				pendingChangeTimers.delete(relativePath);
+			}
+			emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+		}
+	};
+
+	watchDirectory("");
+	for (const [relativePath, entry] of snapshot) {
+		if (entry.isDirectory) watchDirectory(relativePath);
+	}
+
+	const watchApi: Watcher = {
+		ready,
+		on(event: "ready" | WatchEventName, handler: ((file: File) => unknown) | (() => unknown)) {
+			if (event === "ready") {
+				handlers.ready.add(handler as () => unknown);
+				return watchApi;
+			}
+
+			handlers[event].add(handler as (file: File) => unknown);
+			return watchApi;
+		},
+		close: () => {
+			for (const pending of pendingChangeTimers.values()) {
+				clearTimeout(pending);
+			}
+			pendingChangeTimers.clear();
+			for (const watcher of directoryWatchers.values()) {
+				watcher.close();
+			}
+			directoryWatchers.clear();
+		},
+	};
+
+	return watchApi;
+}
+
+function buildSnapshot(
+	directoryPath: string,
+): Map<string, { isDirectory: boolean; fingerprint: string }> {
+	const snapshot = new Map<string, { isDirectory: boolean; fingerprint: string }>();
+	collectSnapshotEntries(directoryPath, directoryPath, snapshot);
+	return snapshot;
+}
+
+/** Never source, and huge: watching every folder inside them could exhaust OS watch limits. */
+const UNWATCHED_DIRECTORIES = new Set(["node_modules", ".git"]);
+
+function collectSnapshotEntries(
+	rootDirectoryPath: string,
+	currentDirectoryPath: string,
+	snapshot: Map<string, { isDirectory: boolean; fingerprint: string }>,
+) {
+	for (const entry of readdirSync(currentDirectoryPath, { encoding: "utf8" })) {
+		const name = typeof entry === "string" ? entry : String(entry);
+		const fullPath = path.join(currentDirectoryPath, name);
+		if (UNWATCHED_DIRECTORIES.has(name)) {
+			continue;
+		}
+		const relativePath = toPosixPath(path.relative(rootDirectoryPath, fullPath));
+		const stat = statSync(fullPath);
+		const snapshotEntry = toSnapshotEntry(stat);
+
+		snapshot.set(relativePath, snapshotEntry);
+
+		if (!snapshotEntry.isDirectory) {
+			continue;
+		}
+
+		collectSnapshotEntries(rootDirectoryPath, fullPath, snapshot);
+	}
+}
+
+function toSnapshotEntry(stat: { isDirectory(): boolean; mtimeMs: number; size: number }) {
+	const isDirectory = stat.isDirectory();
+	return {
+		isDirectory,
+		fingerprint: isDirectory ? `dir:${stat.mtimeMs}` : `file:${stat.mtimeMs}:${stat.size}`,
+	};
+}
+
+function toPosixPath(filePath: string) {
+	return filePath.split(path.sep).join(path.posix.sep);
+}

package/src/io/write-file.ts

@@ -0,0 +1,21 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export type WriteFileOptions = {
+	mkdir?: boolean;
+	encoding?: BufferEncoding;
+};
+
+export async function writeFile(
+	filePath: string,
+	content: string,
+	options: WriteFileOptions = { encoding: "utf8", mkdir: false },
+): Promise<void> {
+	const { encoding, mkdir } = options;
+	if (mkdir) {
+		const directory = path.dirname(filePath);
+		await fs.mkdir(directory, { recursive: true });
+	}
+
+	await fs.writeFile(filePath, content, encoding);
+}

package/src/objects/deep-merge.ts

@@ -0,0 +1,131 @@
+// Source https://github.com/voodoocreation/ts-deepmerge/blob/master/package.json
+
+type TAllKeys<T> = T extends unknown ? keyof T : never;
+
+type TIndexValue<T, K extends PropertyKey, D = never> = T extends unknown
+	? K extends keyof T
+		? T[K]
+		: D
+	: never;
+
+type TPartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>> extends infer O
+	? { [P in keyof O]: O[P] }
+	: never;
+
+type TFunction = (...a: unknown[]) => unknown;
+
+type TPrimitives = string | number | boolean | bigint | symbol | Date | TFunction;
+
+type TMerged<T> = [T] extends [Array<unknown>]
+	? { [K in keyof T]: TMerged<T[K]> }
+	: [T] extends [TPrimitives]
+		? T
+		: [T] extends [object]
+			? TPartialKeys<{ [K in TAllKeys<T>]: TMerged<TIndexValue<T, K>> }, never>
+			: T;
+
+// istanbul ignore next
+const isObject = (obj: unknown) => {
+	if (typeof obj === "object" && obj !== null) {
+		if (typeof Object.getPrototypeOf === "function") {
+			const prototype = Object.getPrototypeOf(obj);
+			return prototype === Object.prototype || prototype === null;
+		}
+
+		return Object.prototype.toString.call(obj) === "[object Object]";
+	}
+
+	return false;
+};
+
+interface IObject {
+	[key: string]: unknown;
+}
+
+export const merge = <T extends object[]>(...objects: T): TMerged<T[number]> =>
+	objects.reduce((result, current) => {
+		if (current === undefined) {
+			return result;
+		}
+
+		if (Array.isArray(current)) {
+			throw new TypeError("Arguments provided to ts-deepmerge must be objects, not arrays.");
+		}
+
+		Object.keys(current).forEach((key) => {
+			if (["__proto__", "constructor", "prototype"].includes(key)) {
+				return;
+			}
+
+			if (Array.isArray(result[key]) && Array.isArray(current[key])) {
+				result[key] = merge.options.mergeArrays
+					? merge.options.uniqueArrayItems
+						? Array.from(new Set((result[key] as unknown[]).concat(current[key])))
+						: [...result[key], ...current[key]]
+					: current[key];
+			} else if (isObject(result[key]) && isObject(current[key])) {
+				result[key] = merge(result[key] as IObject, current[key] as IObject);
+			} else if (!isObject(result[key]) && isObject(current[key])) {
+				result[key] = merge(current[key], undefined);
+			} else {
+				result[key] =
+					current[key] === undefined
+						? merge.options.allowUndefinedOverrides
+							? current[key]
+							: result[key]
+						: current[key];
+			}
+		});
+
+		return result;
+	}, {} as IObject) as TMerged<T[number]>;
+
+interface IOptions {
+	/**
+	 * When `true`, values explicitly provided as `undefined` will override existing values, though properties that are simply omitted won't affect anything.
+	 * When `false`, values explicitly provided as `undefined` won't override existing values.
+	 *
+	 * Default: `true`
+	 */
+	allowUndefinedOverrides: boolean;
+
+	/**
+	 * When `true` it will merge array properties.
+	 * When `false` it will replace array properties with the last instance entirely instead of merging their contents.
+	 *
+	 * Default: `true`
+	 */
+	mergeArrays: boolean;
+
+	/**
+	 * When `true` it will ensure there are no duplicate array items.
+	 * When `false` it will allow duplicates when merging arrays.
+	 *
+	 * Default: `true`
+	 */
+	uniqueArrayItems: boolean;
+}
+
+const defaultOptions: IOptions = {
+	allowUndefinedOverrides: true,
+	mergeArrays: true,
+	uniqueArrayItems: true,
+};
+
+merge.options = defaultOptions;
+
+merge.withOptions = <R = unknown, T extends object[] = object[]>(
+	options: Partial<IOptions>,
+	...objects: T
+): R => {
+	merge.options = {
+		...defaultOptions,
+		...options,
+	};
+
+	const result = merge(...objects);
+
+	merge.options = defaultOptions;
+
+	return result as unknown as R;
+};

package/{es6/src/reflection/index.js → src/reflection/index.ts}

@@ -1,3 +1,4 @@
 import "reflect-metadata";
+
 export * from "./types/index.js";
 export * from "./utilities.js";