@effectionx/fs 0.2.0

package/README.md

@@ -0,0 +1,276 @@
+# FS
+
+File system operations for Effection programs. This package wraps Node.js
+`fs/promises` APIs as Effection Operations with structured concurrency support.
+
+---
+
+## Installation
+
+```bash
+npm install @effectionx/fs
+```
+
+## Basic Usage
+
+```typescript
+import { main } from "effection";
+import { exists, readTextFile, writeTextFile } from "@effectionx/fs";
+
+await main(function* () {
+  if (yield* exists("./config.json")) {
+    const config = yield* readTextFile("./config.json");
+    console.log(JSON.parse(config));
+  } else {
+    yield* writeTextFile("./config.json", JSON.stringify({ version: 1 }));
+  }
+});
+```
+
+## File Operations
+
+### stat()
+
+Get file or directory stats.
+
+```typescript
+import { stat } from "@effectionx/fs";
+
+const stats = yield* stat("./file.txt");
+console.log(stats.isFile()); // true
+console.log(stats.size); // file size in bytes
+```
+
+### lstat()
+
+Get file or directory stats without following symlinks.
+
+```typescript
+import { lstat } from "@effectionx/fs";
+
+const stats = yield* lstat("./symlink");
+console.log(stats.isSymbolicLink()); // true
+```
+
+### exists()
+
+Check if a file or directory exists.
+
+```typescript
+import { exists } from "@effectionx/fs";
+
+if (yield* exists("./config.json")) {
+  console.log("Config file found");
+}
+```
+
+### readTextFile()
+
+Read a file as text.
+
+```typescript
+import { readTextFile } from "@effectionx/fs";
+
+const content = yield* readTextFile("./README.md");
+```
+
+### writeTextFile()
+
+Write text to a file.
+
+```typescript
+import { writeTextFile } from "@effectionx/fs";
+
+yield* writeTextFile("./output.txt", "Hello, World!");
+```
+
+### ensureFile()
+
+Ensure a file exists, creating parent directories and the file if needed.
+
+```typescript
+import { ensureFile } from "@effectionx/fs";
+
+yield* ensureFile("./data/logs/app.log");
+```
+
+### copyFile()
+
+Copy a file.
+
+```typescript
+import { copyFile } from "@effectionx/fs";
+
+yield* copyFile("./source.txt", "./backup.txt");
+```
+
+### rm()
+
+Remove a file or directory.
+
+```typescript
+import { rm } from "@effectionx/fs";
+
+// Remove a file
+yield* rm("./temp.txt");
+
+// Remove a directory recursively
+yield* rm("./temp", { recursive: true });
+
+// Force remove (no error if doesn't exist)
+yield* rm("./maybe-exists", { force: true });
+```
+
+## Directory Operations
+
+### ensureDir()
+
+Ensure a directory exists, creating it recursively if needed.
+
+```typescript
+import { ensureDir } from "@effectionx/fs";
+
+yield* ensureDir("./data/cache/images");
+```
+
+### readdir()
+
+Read the contents of a directory.
+
+```typescript
+import { readdir } from "@effectionx/fs";
+
+const entries = yield* readdir("./src");
+console.log(entries); // ["index.ts", "utils.ts", ...]
+```
+
+### emptyDir()
+
+Empty a directory by removing all its contents. Creates the directory if it
+doesn't exist.
+
+```typescript
+import { emptyDir } from "@effectionx/fs";
+
+yield* emptyDir("./dist");
+```
+
+### walk()
+
+Walk a directory tree and yield entries as a Stream.
+
+```typescript
+import { walk } from "@effectionx/fs";
+import { each } from "effection";
+
+for (const entry of yield* each(walk("./src"))) {
+  if (entry.isFile && entry.name.endsWith(".ts")) {
+    console.log(entry.path);
+  }
+  yield* each.next();
+}
+```
+
+Each entry includes:
+- `path` - Full path to the entry
+- `name` - Basename of the entry
+- `isFile` - Whether it's a file
+- `isDirectory` - Whether it's a directory
+- `isSymlink` - Whether it's a symbolic link
+
+#### Walk Options
+
+```typescript
+walk("./src", {
+  includeDirs: true,      // Include directories (default: true)
+  includeFiles: true,     // Include files (default: true)
+  includeSymlinks: true,  // Include symlinks (default: true)
+  match: [/\.ts$/],       // Only include matching paths
+  skip: [/node_modules/], // Exclude matching paths
+  maxDepth: 3,            // Maximum traversal depth
+  followSymlinks: false,  // Follow symbolic links (default: false)
+});
+```
+
+### expandGlob()
+
+Expand glob patterns and yield matching paths as a Stream.
+
+```typescript
+import { expandGlob } from "@effectionx/fs";
+import { each } from "effection";
+
+for (const entry of yield* each(expandGlob("./src/**/*.ts"))) {
+  console.log(entry.path);
+  yield* each.next();
+}
+```
+
+#### Glob Options
+
+```typescript
+expandGlob("**/*.ts", {
+  root: "./src",          // Root directory (default: ".")
+  exclude: ["**/*.test.ts"], // Patterns to exclude
+  includeDirs: false,     // Include directories (default: true)
+  followSymlinks: false,  // Follow symbolic links (default: false)
+});
+```
+
+## Utilities
+
+### toPath()
+
+Convert a path or URL to a file path string.
+
+```typescript
+import { toPath } from "@effectionx/fs";
+
+toPath("./file.txt");           // "./file.txt"
+toPath(new URL("file:///tmp")); // "/tmp"
+```
+
+### globToRegExp()
+
+Convert a glob pattern to a RegExp.
+
+```typescript
+import { globToRegExp } from "@effectionx/fs";
+
+const regex = globToRegExp("*.ts");
+regex.test("file.ts");  // true
+regex.test("file.js");  // false
+
+// Supports extended glob syntax
+globToRegExp("**/*.{ts,js}");     // Match .ts or .js files recursively
+globToRegExp("file[0-9].txt");    // Character classes
+globToRegExp("src/**/test?.ts");  // ? matches single character
+```
+
+### URL Conversion
+
+Re-exported from `node:url` for convenience:
+
+```typescript
+import { fromFileUrl, toFileUrl } from "@effectionx/fs";
+
+fromFileUrl(new URL("file:///tmp/file.txt")); // "/tmp/file.txt"
+toFileUrl("/tmp/file.txt");                    // URL { href: "file:///tmp/file.txt" }
+```
+
+## Path and URL Support
+
+All file operations accept either a string path or a `URL` object:
+
+```typescript
+import { readTextFile } from "@effectionx/fs";
+
+// String path
+yield* readTextFile("./config.json");
+
+// URL object
+yield* readTextFile(new URL("file:///etc/config.json"));
+
+// import.meta.url based paths
+yield* readTextFile(new URL("./data.json", import.meta.url));
+```

package/dist/mod.d.ts

@@ -0,0 +1,223 @@
+import type { Stats } from "node:fs";
+import { type Operation, type Stream } from "effection";
+/**
+ * Convert a path or URL to a file path string
+ */
+export declare function toPath(pathOrUrl: string | URL): string;
+/**
+ * Get file or directory stats
+ *
+ * @example
+ * ```ts
+ * import { stat } from "@effectionx/fs";
+ *
+ * const stats = yield* stat("./file.txt");
+ * console.log(stats.isFile());
+ * ```
+ */
+export declare function stat(pathOrUrl: string | URL): Operation<Stats>;
+/**
+ * Get file or directory stats without following symlinks
+ *
+ * @example
+ * ```ts
+ * import { lstat } from "@effectionx/fs";
+ *
+ * const stats = yield* lstat("./symlink");
+ * console.log(stats.isSymbolicLink());
+ * ```
+ */
+export declare function lstat(pathOrUrl: string | URL): Operation<Stats>;
+/**
+ * Check if a file or directory exists
+ *
+ * @example
+ * ```ts
+ * import { exists } from "@effectionx/fs";
+ *
+ * if (yield* exists("./config.json")) {
+ *   console.log("Config file found");
+ * }
+ * ```
+ */
+export declare function exists(pathOrUrl: string | URL): Operation<boolean>;
+/**
+ * Ensure a directory exists, creating it recursively if needed
+ *
+ * @example
+ * ```ts
+ * import { ensureDir } from "@effectionx/fs";
+ *
+ * yield* ensureDir("./data/cache");
+ * ```
+ */
+export declare function ensureDir(pathOrUrl: string | URL): Operation<void>;
+/**
+ * Ensure a file exists, creating parent directories and the file if needed
+ *
+ * @example
+ * ```ts
+ * import { ensureFile } from "@effectionx/fs";
+ *
+ * yield* ensureFile("./data/config.json");
+ * ```
+ */
+export declare function ensureFile(pathOrUrl: string | URL): Operation<void>;
+/**
+ * Read the contents of a directory
+ *
+ * @example
+ * ```ts
+ * import { readdir } from "@effectionx/fs";
+ *
+ * const entries = yield* readdir("./src");
+ * ```
+ */
+export declare function readdir(pathOrUrl: string | URL): Operation<string[]>;
+/**
+ * Empty a directory by removing all its contents.
+ * Creates the directory if it doesn't exist.
+ *
+ * @example
+ * ```ts
+ * import { emptyDir } from "@effectionx/fs";
+ *
+ * yield* emptyDir("./dist");
+ * ```
+ */
+export declare function emptyDir(pathOrUrl: string | URL): Operation<void>;
+/**
+ * Remove a file or directory
+ *
+ * @example
+ * ```ts
+ * import { rm } from "@effectionx/fs";
+ *
+ * yield* rm("./temp", { recursive: true });
+ * ```
+ */
+export declare function rm(pathOrUrl: string | URL, options?: {
+    recursive?: boolean;
+    force?: boolean;
+}): Operation<void>;
+/**
+ * Copy a file
+ *
+ * @example
+ * ```ts
+ * import { copyFile } from "@effectionx/fs";
+ *
+ * yield* copyFile("./source.txt", "./dest.txt");
+ * ```
+ */
+export declare function copyFile(src: string | URL, dest: string | URL): Operation<void>;
+/**
+ * Read a file as text
+ *
+ * @example
+ * ```ts
+ * import { readTextFile } from "@effectionx/fs";
+ *
+ * const content = yield* readTextFile("./config.json");
+ * ```
+ */
+export declare function readTextFile(pathOrUrl: string | URL): Operation<string>;
+/**
+ * Write text to a file
+ *
+ * @example
+ * ```ts
+ * import { writeTextFile } from "@effectionx/fs";
+ *
+ * yield* writeTextFile("./output.txt", "Hello, World!");
+ * ```
+ */
+export declare function writeTextFile(pathOrUrl: string | URL, content: string): Operation<void>;
+/**
+ * Entry returned by walk()
+ */
+export interface WalkEntry {
+    /** Full path to the entry */
+    path: string;
+    /** Name of the entry (basename) */
+    name: string;
+    /** Whether the entry is a file */
+    isFile: boolean;
+    /** Whether the entry is a directory */
+    isDirectory: boolean;
+    /** Whether the entry is a symbolic link */
+    isSymlink: boolean;
+}
+/**
+ * Options for walk()
+ */
+export interface WalkOptions {
+    /** Include directories in results (default: true) */
+    includeDirs?: boolean;
+    /** Include files in results (default: true) */
+    includeFiles?: boolean;
+    /** Include symbolic links in results (default: true) */
+    includeSymlinks?: boolean;
+    /** Only include entries matching these patterns */
+    match?: RegExp[];
+    /** Exclude entries matching these patterns */
+    skip?: RegExp[];
+    /** Maximum depth to traverse (default: Infinity) */
+    maxDepth?: number;
+    /** Follow symbolic links (default: false) */
+    followSymlinks?: boolean;
+}
+/**
+ * Walk a directory tree and yield entries as a Stream
+ *
+ * @example
+ * ```ts
+ * import { walk } from "@effectionx/fs";
+ * import { each } from "effection";
+ *
+ * for (const entry of yield* each(walk("./src"))) {
+ *   if (entry.isFile && entry.name.endsWith(".ts")) {
+ *     console.log(entry.path);
+ *   }
+ *   yield* each.next();
+ * }
+ * ```
+ */
+export declare function walk(root: string | URL, options?: WalkOptions): Stream<WalkEntry, void>;
+/**
+ * Expand glob patterns and yield matching paths as a Stream
+ *
+ * @example
+ * ```ts
+ * import { expandGlob } from "@effectionx/fs";
+ * import { each } from "effection";
+ *
+ * for (const entry of yield* each(expandGlob("./src/*.ts"))) {
+ *   console.log(entry.path);
+ *   yield* each.next();
+ * }
+ * ```
+ */
+export declare function expandGlob(glob: string, options?: {
+    root?: string;
+    exclude?: string[];
+    includeDirs?: boolean;
+    followSymlinks?: boolean;
+}): Stream<WalkEntry, void>;
+/**
+ * Convert a glob pattern to a RegExp
+ *
+ * @example
+ * ```ts
+ * import { globToRegExp } from "@effectionx/fs";
+ *
+ * const regex = globToRegExp("*.ts");
+ * console.log(regex.test("file.ts")); // true
+ * ```
+ */
+export declare function globToRegExp(glob: string, options?: {
+    extended?: boolean;
+    globstar?: boolean;
+}): RegExp;
+export { fileURLToPath as fromFileUrl, pathToFileURL as toFileUrl, } from "node:url";
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"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"}