@anabranch/fs 0.2.3 → 0.3.0

package/esm/index.d.ts

@@ -32,7 +32,9 @@ export { glob, readDir, walk } from './dir.js';
 export type { DirError } from './dir.js';
 export { watch } from './watch.js';
 export type { WatchError } from './watch.js';
-export type { DirEntry, FsEvent, GlobOptions, WalkEntry, WalkOptions, WatchOptions, } from './types.js';
-export { FSError } from './errors.js';
+export { copyFile, ensureDir, exists, remove, stat } from './util.js';
+export type { CopyFileError, EnsureDirError, ExistsError, RemoveError, StatError, } from './util.js';
+export type { DirEntry, FsEvent, GlobOptions, StatInfo, WalkEntry, WalkOptions, WatchOptions, } from './types.js';
+export { FSError, nodeErrorToFSError } from './errors.js';
 export { AlreadyExists, InvalidData, IsDirectory, NotDirectory, NotFound, PermissionDenied, ReadError, Unknown, WriteError, } from './errors.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,qBAAqB,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACvE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,QAAQ,EACR,OAAO,EACP,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,UAAU,GACX,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,qBAAqB,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACvE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACrE,YAAY,EACV,aAAa,EACb,cAAc,EACd,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,WAAW,CAAA;AAClB,YAAY,EACV,QAAQ,EACR,OAAO,EACP,WAAW,EACX,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,UAAU,GACX,MAAM,aAAa,CAAA"}

package/esm/index.js

@@ -28,5 +28,6 @@ export { readFile, readJson, readLines, readTextFile } from './read.js';
 export { writeFile, writeJson, writeTextFile } from './write.js';
 export { glob, readDir, walk } from './dir.js';
 export { watch } from './watch.js';
-export { FSError } from './errors.js';
+export { copyFile, ensureDir, exists, remove, stat } from './util.js';
+export { FSError, nodeErrorToFSError } from './errors.js';
 export { AlreadyExists, InvalidData, IsDirectory, NotDirectory, NotFound, PermissionDenied, ReadError, Unknown, WriteError, } from './errors.js';

package/esm/types.d.ts

@@ -49,6 +49,23 @@ export interface WalkOptions {
 /** Options for {@link glob}. Same as {@link WalkOptions} without `match`. */
 export interface GlobOptions extends Omit<WalkOptions, 'match'> {
 }
+/** File metadata returned by {@link stat}. */
+export interface StatInfo {
+    /** Size in bytes. */
+    size: number;
+    /** Whether the path is a regular file. */
+    isFile: boolean;
+    /** Whether the path is a directory. */
+    isDirectory: boolean;
+    /** Whether the path is a symbolic link. */
+    isSymlink: boolean;
+    /** Last modification time. */
+    mtime: Date;
+    /** Last access time. */
+    atime: Date;
+    /** Creation time. */
+    birthtime: Date;
+}
 /** A file-system change event, as yielded by {@link watch}. */
 export interface FsEvent {
     /** The type of change. */

package/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAA;IACf,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAA;IACpB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;CAAG;AAElE,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAA;IACf,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAA;IACpB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;CAAG;AAElE,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,MAAM,EAAE,OAAO,CAAA;IACf,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAA;IACpB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAA;IAClB,8BAA8B;IAC9B,KAAK,EAAE,IAAI,CAAA;IACX,wBAAwB;IACxB,KAAK,EAAE,IAAI,CAAA;IACX,qBAAqB;IACrB,SAAS,EAAE,IAAI,CAAA;CAChB;AAED,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB"}

package/esm/util.d.ts

@@ -0,0 +1,62 @@
+import { Task } from 'anabranch';
+import { type NotFound, type PermissionDenied, type Unknown } from './errors.js';
+import type { StatInfo } from './types.js';
+/**
+ * Checks whether a path exists.
+ *
+ * @example
+ * ```ts
+ * if (await exists("./config.json").run()) {
+ *   // file exists
+ * }
+ * ```
+ */
+export declare function exists(path: string | URL): Task<boolean, ExistsError>;
+/** Errors that can occur when checking existence. */
+export type ExistsError = PermissionDenied | Unknown;
+/**
+ * Creates a directory and any missing parents, like `mkdir -p`.
+ *
+ * @example
+ * ```ts
+ * await ensureDir("./data/cache/images").run();
+ * ```
+ */
+export declare function ensureDir(path: string | URL): Task<void, EnsureDirError>;
+/** Errors that can occur when ensuring a directory. */
+export type EnsureDirError = PermissionDenied | Unknown;
+/**
+ * Removes a file or directory recursively. No error if the path doesn't exist.
+ *
+ * @example
+ * ```ts
+ * await remove("./tmp").run();
+ * ```
+ */
+export declare function remove(path: string | URL): Task<void, RemoveError>;
+/** Errors that can occur when removing a path. */
+export type RemoveError = PermissionDenied | Unknown;
+/**
+ * Copies a single file from `src` to `dst`.
+ *
+ * @example
+ * ```ts
+ * await copyFile("./template.txt", "./output.txt").run();
+ * ```
+ */
+export declare function copyFile(src: string | URL, dst: string | URL): Task<void, CopyFileError>;
+/** Errors that can occur when copying a file. */
+export type CopyFileError = NotFound | PermissionDenied | Unknown;
+/**
+ * Returns metadata for a path without reading its contents.
+ *
+ * @example
+ * ```ts
+ * const info = await stat("./data.csv").run();
+ * console.log(info.size, info.mtime);
+ * ```
+ */
+export declare function stat(path: string | URL): Task<StatInfo, StatError>;
+/** Errors that can occur when stat-ing a path. */
+export type StatError = NotFound | PermissionDenied | Unknown;
+//# sourceMappingURL=util.d.ts.map

package/esm/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACb,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAWrE;AAED,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAIxE;AAED,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,OAAO,CAAA;AAEvD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAIlE;AAED,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,GAAG,EAAE,MAAM,GAAG,GAAG,GAChB,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAI3B;AAED,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAA;AAEjE;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAalE;AAED,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAA"}

package/esm/util.js

@@ -0,0 +1,89 @@
+import { access, copyFile as fsCopyFile, lstat, mkdir, rm, } from 'node:fs/promises';
+import { Task } from 'anabranch';
+import { nodeErrorToFSError, } from './errors.js';
+/**
+ * Checks whether a path exists.
+ *
+ * @example
+ * ```ts
+ * if (await exists("./config.json").run()) {
+ *   // file exists
+ * }
+ * ```
+ */
+export function exists(path) {
+    return Task.of(async () => {
+        try {
+            await access(path);
+            return true;
+        }
+        catch (error) {
+            const fsError = nodeErrorToFSError(error, path);
+            if (fsError.kind === 'NotFound')
+                return false;
+            throw fsError;
+        }
+    });
+}
+/**
+ * Creates a directory and any missing parents, like `mkdir -p`.
+ *
+ * @example
+ * ```ts
+ * await ensureDir("./data/cache/images").run();
+ * ```
+ */
+export function ensureDir(path) {
+    return Task.of(async () => {
+        await mkdir(path, { recursive: true });
+    }).mapErr((error) => nodeErrorToFSError(error, path));
+}
+/**
+ * Removes a file or directory recursively. No error if the path doesn't exist.
+ *
+ * @example
+ * ```ts
+ * await remove("./tmp").run();
+ * ```
+ */
+export function remove(path) {
+    return Task.of(async () => {
+        await rm(path, { recursive: true, force: true });
+    }).mapErr((error) => nodeErrorToFSError(error, path));
+}
+/**
+ * Copies a single file from `src` to `dst`.
+ *
+ * @example
+ * ```ts
+ * await copyFile("./template.txt", "./output.txt").run();
+ * ```
+ */
+export function copyFile(src, dst) {
+    return Task.of(async () => {
+        await fsCopyFile(src, dst);
+    }).mapErr((error) => nodeErrorToFSError(error, src));
+}
+/**
+ * Returns metadata for a path without reading its contents.
+ *
+ * @example
+ * ```ts
+ * const info = await stat("./data.csv").run();
+ * console.log(info.size, info.mtime);
+ * ```
+ */
+export function stat(path) {
+    return Task.of(async () => {
+        const s = await lstat(path);
+        return {
+            size: s.size,
+            isFile: s.isFile(),
+            isDirectory: s.isDirectory(),
+            isSymlink: s.isSymbolicLink(),
+            mtime: s.mtimeMs ? new Date(s.mtimeMs) : s.mtime,
+            atime: s.atimeMs ? new Date(s.atimeMs) : s.atime,
+            birthtime: s.birthtimeMs ? new Date(s.birthtimeMs) : s.birthtime,
+        };
+    }).mapErr((error) => nodeErrorToFSError(error, path));
+}

package/esm/watch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAA;AAEpB,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAiC7B"}
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAA;AAEpB,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAgC7B"}

package/esm/watch.js

@@ -29,9 +29,8 @@ export function watch(path, options) {
             }
             channel.send({ kind, paths: [fullPath] });
         });
-        const channel = new Channel({
-            onClose: () => watcher?.close(),
-        });
+        const channel = Channel.create()
+            .withOnClose(() => watcher?.close());
         watcher.once('error', (err) => channel.fail(nodeErrorToFSError(err, path)));
         watcher.once('close', () => channel.close());
         yield* channel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anabranch/fs",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Streaming file-system utilities for reading, walking, globbing, and watching files with composable error handling.",
   "repository": {
     "type": "git",