@intellectual-frontiers/system 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/compile.d.ts +94 -0
- package/dist/compile.js +130 -0
- package/dist/dirs.d.ts +19 -0
- package/dist/dirs.js +64 -0
- package/dist/discover.d.ts +43 -0
- package/dist/discover.js +118 -0
- package/dist/errors.d.ts +130 -0
- package/dist/errors.js +189 -0
- package/dist/fs.d.ts +263 -0
- package/dist/fs.js +826 -0
- package/dist/git.d.ts +63 -0
- package/dist/git.js +144 -0
- package/dist/job-plan.d.ts +207 -0
- package/dist/job-plan.js +563 -0
- package/dist/lock.d.ts +41 -0
- package/dist/lock.js +130 -0
- package/dist/mod.d.ts +28 -0
- package/dist/mod.js +29 -0
- package/dist/path.d.ts +47 -0
- package/dist/path.js +55 -0
- package/dist/proc.d.ts +257 -0
- package/dist/proc.js +589 -0
- package/dist/schedule.d.ts +99 -0
- package/dist/schedule.js +131 -0
- package/dist/stdio.d.ts +31 -0
- package/dist/stdio.js +170 -0
- package/dist/tty.d.ts +34 -0
- package/dist/tty.js +71 -0
- package/dist/watch.d.ts +42 -0
- package/dist/watch.js +342 -0
- package/package.json +113 -4
- package/src/compile.ts +178 -0
- package/src/dirs.ts +87 -0
- package/src/discover.ts +144 -0
- package/src/errors.ts +176 -0
- package/src/fs.ts +967 -0
- package/src/git.ts +163 -0
- package/src/job-plan.ts +660 -0
- package/src/lock.ts +149 -0
- package/src/mod.ts +29 -0
- package/src/path.ts +59 -0
- package/src/proc.ts +786 -0
- package/src/schedule.ts +173 -0
- package/src/stdio.ts +204 -0
- package/src/tty.ts +94 -0
- package/src/watch.ts +338 -0
package/dist/errors.js
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
// Spec: 0001-system FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The errors the runtime throws (commons 0005-typescript-runtime FR-019): one class for each kind a caller acts on, by plain names (`errors.NotFound`), each made from the `code` Node gives
|
|
4
|
+
* (`ENOENT`, `EEXIST`, `EACCES`, ...), keeping that code, the path or address where there is one, and the original error as its `cause`.
|
|
5
|
+
* The runtime throws; `Result` belongs to the layers above, which turn these into their own errors.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { errors } from "./errors.ts";
|
|
10
|
+
* import { readTextFile } from "./fs.ts";
|
|
11
|
+
* try {
|
|
12
|
+
* await readTextFile("/no/such/file");
|
|
13
|
+
* } catch (e) {
|
|
14
|
+
* if (e instanceof errors.NotFound) console.log("not there");
|
|
15
|
+
* else throw e;
|
|
16
|
+
* }
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* @module
|
|
20
|
+
*/
|
|
21
|
+
/** What every error of the runtime carries: the code the host gave and, for a file or an address, where. */
|
|
22
|
+
export class RuntimeError extends Error {
|
|
23
|
+
/** The host's error code (`ENOENT`, `EACCES`, ...), or `""` where it gave none. */
|
|
24
|
+
code;
|
|
25
|
+
/** The path, or the address, the failed call was about, where there was one. */
|
|
26
|
+
path;
|
|
27
|
+
/** Make one from a message, the host's code, the path and the error it stands for. */
|
|
28
|
+
constructor(message, code, path, cause) {
|
|
29
|
+
super(message, cause === undefined ? undefined : { cause });
|
|
30
|
+
this.code = code;
|
|
31
|
+
this.path = path;
|
|
32
|
+
}
|
|
33
|
+
/** The class's own name, so a stack trace says `NotFound` and not `Error`. */
|
|
34
|
+
get name() {
|
|
35
|
+
return this.constructor.name;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
/** Nothing is at the path, or no such program (`ENOENT`). */
|
|
39
|
+
export class NotFound extends RuntimeError {
|
|
40
|
+
}
|
|
41
|
+
/** Something is already at the path (`EEXIST`). */
|
|
42
|
+
export class AlreadyExists extends RuntimeError {
|
|
43
|
+
}
|
|
44
|
+
/** The account may not do this (`EACCES`, `EPERM`). */
|
|
45
|
+
export class PermissionDenied extends RuntimeError {
|
|
46
|
+
}
|
|
47
|
+
/** A folder was given where a file was needed (`EISDIR`). */
|
|
48
|
+
export class IsADirectory extends RuntimeError {
|
|
49
|
+
}
|
|
50
|
+
/** A file was given where a folder was needed (`ENOTDIR`). */
|
|
51
|
+
export class NotADirectory extends RuntimeError {
|
|
52
|
+
}
|
|
53
|
+
/** A folder that must be empty is not (`ENOTEMPTY`). */
|
|
54
|
+
export class DirectoryNotEmpty extends RuntimeError {
|
|
55
|
+
}
|
|
56
|
+
/** Links point at each other with no end (`ELOOP`). */
|
|
57
|
+
export class FilesystemLoop extends RuntimeError {
|
|
58
|
+
}
|
|
59
|
+
/** The resource is in use (`EBUSY`, `ETXTBSY`). */
|
|
60
|
+
export class Busy extends RuntimeError {
|
|
61
|
+
}
|
|
62
|
+
/** The address is already in use (`EADDRINUSE`). */
|
|
63
|
+
export class AddrInUse extends RuntimeError {
|
|
64
|
+
}
|
|
65
|
+
/** The address cannot be used on this computer (`EADDRNOTAVAIL`). */
|
|
66
|
+
export class AddrNotAvailable extends RuntimeError {
|
|
67
|
+
}
|
|
68
|
+
/** Nothing listens at the address (`ECONNREFUSED`). */
|
|
69
|
+
export class ConnectionRefused extends RuntimeError {
|
|
70
|
+
}
|
|
71
|
+
/** The other end reset the connection (`ECONNRESET`). */
|
|
72
|
+
export class ConnectionReset extends RuntimeError {
|
|
73
|
+
}
|
|
74
|
+
/** The connection was aborted (`ECONNABORTED`). */
|
|
75
|
+
export class ConnectionAborted extends RuntimeError {
|
|
76
|
+
}
|
|
77
|
+
/** The other end of a pipe was closed (`EPIPE`). */
|
|
78
|
+
export class BrokenPipe extends RuntimeError {
|
|
79
|
+
}
|
|
80
|
+
/** The call took too long (`ETIMEDOUT`). */
|
|
81
|
+
export class TimedOut extends RuntimeError {
|
|
82
|
+
}
|
|
83
|
+
/** A signal interrupted the call (`EINTR`). */
|
|
84
|
+
export class Interrupted extends RuntimeError {
|
|
85
|
+
}
|
|
86
|
+
/** The network cannot be reached (`ENETUNREACH`, `EHOSTUNREACH`). */
|
|
87
|
+
export class NetworkUnreachable extends RuntimeError {
|
|
88
|
+
}
|
|
89
|
+
/** The data was not what was expected (`EINVAL` on data, a bad archive or encoding). */
|
|
90
|
+
export class InvalidData extends RuntimeError {
|
|
91
|
+
}
|
|
92
|
+
/** This platform or file system cannot do it (`ENOSYS`, `ENOTSUP`, `EXDEV` across devices). */
|
|
93
|
+
export class NotSupported extends RuntimeError {
|
|
94
|
+
}
|
|
95
|
+
/** The end of the data came before what was needed. */
|
|
96
|
+
export class UnexpectedEof extends RuntimeError {
|
|
97
|
+
}
|
|
98
|
+
/** The error classes by name. */
|
|
99
|
+
export const errors = {
|
|
100
|
+
RuntimeError,
|
|
101
|
+
NotFound,
|
|
102
|
+
AlreadyExists,
|
|
103
|
+
PermissionDenied,
|
|
104
|
+
IsADirectory,
|
|
105
|
+
NotADirectory,
|
|
106
|
+
DirectoryNotEmpty,
|
|
107
|
+
FilesystemLoop,
|
|
108
|
+
Busy,
|
|
109
|
+
AddrInUse,
|
|
110
|
+
AddrNotAvailable,
|
|
111
|
+
ConnectionRefused,
|
|
112
|
+
ConnectionReset,
|
|
113
|
+
ConnectionAborted,
|
|
114
|
+
BrokenPipe,
|
|
115
|
+
TimedOut,
|
|
116
|
+
Interrupted,
|
|
117
|
+
NetworkUnreachable,
|
|
118
|
+
InvalidData,
|
|
119
|
+
NotSupported,
|
|
120
|
+
UnexpectedEof,
|
|
121
|
+
};
|
|
122
|
+
/** The class each Node error code becomes. */
|
|
123
|
+
export const BY_CODE = {
|
|
124
|
+
ENOENT: NotFound,
|
|
125
|
+
EEXIST: AlreadyExists,
|
|
126
|
+
EACCES: PermissionDenied,
|
|
127
|
+
EPERM: PermissionDenied,
|
|
128
|
+
EISDIR: IsADirectory,
|
|
129
|
+
ENOTDIR: NotADirectory,
|
|
130
|
+
ENOTEMPTY: DirectoryNotEmpty,
|
|
131
|
+
ELOOP: FilesystemLoop,
|
|
132
|
+
EBUSY: Busy,
|
|
133
|
+
ETXTBSY: Busy,
|
|
134
|
+
EADDRINUSE: AddrInUse,
|
|
135
|
+
EADDRNOTAVAIL: AddrNotAvailable,
|
|
136
|
+
ECONNREFUSED: ConnectionRefused,
|
|
137
|
+
ECONNRESET: ConnectionReset,
|
|
138
|
+
ECONNABORTED: ConnectionAborted,
|
|
139
|
+
EPIPE: BrokenPipe,
|
|
140
|
+
ETIMEDOUT: TimedOut,
|
|
141
|
+
EINTR: Interrupted,
|
|
142
|
+
ENETUNREACH: NetworkUnreachable,
|
|
143
|
+
EHOSTUNREACH: NetworkUnreachable,
|
|
144
|
+
EINVAL: InvalidData,
|
|
145
|
+
ENOSYS: NotSupported,
|
|
146
|
+
ENOTSUP: NotSupported,
|
|
147
|
+
EXDEV: NotSupported,
|
|
148
|
+
};
|
|
149
|
+
const field = (e, key) => {
|
|
150
|
+
const v = Reflect.get(e, key);
|
|
151
|
+
return typeof v === "string" ? v : undefined;
|
|
152
|
+
};
|
|
153
|
+
/** What was thrown or rejected, as an `Error`: an `Error` as it is, anything else wrapped, kept as the cause. */
|
|
154
|
+
export function toError(thrown, message = "a value that is not an Error was thrown") {
|
|
155
|
+
return thrown instanceof Error ? thrown : new Error(message, { cause: thrown });
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* What the host threw, as an error of the runtime: an error that carries a known `code` becomes its class (keeping the message, code,
|
|
159
|
+
* path and the original as its cause); any other `Error`, a runtime error among them, is returned as it is; anything else is wrapped by
|
|
160
|
+
* {@link toError}.
|
|
161
|
+
*/
|
|
162
|
+
export function mapError(thrown, path) {
|
|
163
|
+
if (thrown instanceof RuntimeError || typeof thrown !== "object" || thrown === null)
|
|
164
|
+
return toError(thrown);
|
|
165
|
+
const code = field(thrown, "code");
|
|
166
|
+
const Class = code === undefined ? undefined : BY_CODE[code];
|
|
167
|
+
if (code === undefined || Class === undefined)
|
|
168
|
+
return toError(thrown);
|
|
169
|
+
const message = thrown instanceof Error ? thrown.message : (field(thrown, "message") ?? code);
|
|
170
|
+
return new Class(message, code, field(thrown, "path") ?? field(thrown, "address") ?? path, thrown);
|
|
171
|
+
}
|
|
172
|
+
/** Run a call on the host and throw what it throws as an error of the runtime. */
|
|
173
|
+
export async function hostCall(path, f) {
|
|
174
|
+
try {
|
|
175
|
+
return await f();
|
|
176
|
+
}
|
|
177
|
+
catch (e) {
|
|
178
|
+
throw mapError(e, path);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
/** The same, for a call that does not wait. */
|
|
182
|
+
export function hostCallSync(path, f) {
|
|
183
|
+
try {
|
|
184
|
+
return f();
|
|
185
|
+
}
|
|
186
|
+
catch (e) {
|
|
187
|
+
throw mapError(e, path);
|
|
188
|
+
}
|
|
189
|
+
}
|
package/dist/fs.d.ts
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
import { type GlobOptions } from "@intellectual-frontiers/formats/glob";
|
|
2
|
+
import type { Sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
3
|
+
/** A path, as a string or a `file:` URL. */
|
|
4
|
+
export type PathLike = string | URL;
|
|
5
|
+
/** What `stat` knows of a file, by these names. A time the file system does not keep is `null`. */
|
|
6
|
+
export type FileInfo = {
|
|
7
|
+
readonly isFile: boolean;
|
|
8
|
+
readonly isDirectory: boolean;
|
|
9
|
+
readonly isSymlink: boolean;
|
|
10
|
+
readonly size: number;
|
|
11
|
+
readonly mtime: Date | null;
|
|
12
|
+
readonly atime: Date | null;
|
|
13
|
+
readonly birthtime: Date | null;
|
|
14
|
+
readonly ctime: Date | null;
|
|
15
|
+
readonly mode: number | null;
|
|
16
|
+
readonly uid: number | null;
|
|
17
|
+
readonly gid: number | null;
|
|
18
|
+
readonly dev: number;
|
|
19
|
+
readonly ino: number | null;
|
|
20
|
+
readonly nlink: number | null;
|
|
21
|
+
};
|
|
22
|
+
/** One entry of a folder, by these names. */
|
|
23
|
+
export type DirEntry = {
|
|
24
|
+
readonly name: string;
|
|
25
|
+
readonly isFile: boolean;
|
|
26
|
+
readonly isDirectory: boolean;
|
|
27
|
+
readonly isSymlink: boolean;
|
|
28
|
+
};
|
|
29
|
+
/** How to write a file: append instead of replacing, refuse to make it (`create: false`), refuse where it exists (`createNew`), its mode. */
|
|
30
|
+
export type WriteFileOptions = {
|
|
31
|
+
readonly append?: boolean;
|
|
32
|
+
readonly create?: boolean;
|
|
33
|
+
readonly createNew?: boolean;
|
|
34
|
+
readonly mode?: number;
|
|
35
|
+
};
|
|
36
|
+
/** A file's text, read as UTF-8. */
|
|
37
|
+
export declare function readTextFile(path: PathLike): Promise<string>;
|
|
38
|
+
/** A file's text, read as UTF-8, without waiting. */
|
|
39
|
+
export declare function readTextFileSync(path: PathLike): string;
|
|
40
|
+
/** A file's bytes. */
|
|
41
|
+
export declare function readFile(path: PathLike): Promise<Uint8Array>;
|
|
42
|
+
/** A file's bytes, without waiting. */
|
|
43
|
+
export declare function readFileSync(path: PathLike): Uint8Array;
|
|
44
|
+
/** Text written to a file as UTF-8, replacing it unless `append`. */
|
|
45
|
+
export declare function writeTextFile(path: PathLike, data: string, options?: WriteFileOptions): Promise<void>;
|
|
46
|
+
/** Text written to a file as UTF-8, without waiting. */
|
|
47
|
+
export declare function writeTextFileSync(path: PathLike, data: string, options?: WriteFileOptions): void;
|
|
48
|
+
/** Bytes written to a file, replacing it unless `append`. */
|
|
49
|
+
export declare function writeFile(path: PathLike, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
|
|
50
|
+
/** Bytes written to a file, without waiting. */
|
|
51
|
+
export declare function writeFileSync(path: PathLike, data: Uint8Array, options?: WriteFileOptions): void;
|
|
52
|
+
/** How to remove: a folder and everything in it only with `recursive`. */
|
|
53
|
+
export type RemoveOptions = {
|
|
54
|
+
readonly recursive?: boolean;
|
|
55
|
+
};
|
|
56
|
+
/** A file, a link or an empty folder removed; with `recursive`, a folder and everything in it. `NotFound` where nothing is there; the error is of `./errors.ts`. */
|
|
57
|
+
export declare function remove(path: PathLike, options?: RemoveOptions): Promise<void>;
|
|
58
|
+
/** The same, without waiting. */
|
|
59
|
+
export declare function removeSync(path: PathLike, options?: RemoveOptions): void;
|
|
60
|
+
/** How to make a folder: its parents too (and no error where it exists) with `recursive`, and its mode. */
|
|
61
|
+
export type MkdirOptions = {
|
|
62
|
+
readonly recursive?: boolean;
|
|
63
|
+
readonly mode?: number;
|
|
64
|
+
};
|
|
65
|
+
/** A folder made. */
|
|
66
|
+
export declare function mkdir(path: PathLike, options?: MkdirOptions): Promise<void>;
|
|
67
|
+
/** A folder made, without waiting. */
|
|
68
|
+
export declare function mkdirSync(path: PathLike, options?: MkdirOptions): void;
|
|
69
|
+
/** What is at a path, following links. */
|
|
70
|
+
export declare function stat(path: PathLike): Promise<FileInfo>;
|
|
71
|
+
/** What is at a path, following links, without waiting. */
|
|
72
|
+
export declare function statSync(path: PathLike): FileInfo;
|
|
73
|
+
/** What is at a path; a link is described, not followed. */
|
|
74
|
+
export declare function lstat(path: PathLike): Promise<FileInfo>;
|
|
75
|
+
/** What is at a path; a link is described, not followed; without waiting. */
|
|
76
|
+
export declare function lstatSync(path: PathLike): FileInfo;
|
|
77
|
+
/** The entries of a folder, in the order the file system gives them (FR-048); `NotFound` at the first step where it is not there. */
|
|
78
|
+
export declare function readDir(path: PathLike): AsyncIterable<DirEntry>;
|
|
79
|
+
/** The entries of a folder, without waiting. */
|
|
80
|
+
export declare function readDirSync(path: PathLike): DirEntry[];
|
|
81
|
+
/** Where and how a temporary file or folder is named: in `dir` (the system's by default), with a `prefix` and `suffix`. */
|
|
82
|
+
export type MakeTempOptions = {
|
|
83
|
+
readonly dir?: string;
|
|
84
|
+
readonly prefix?: string;
|
|
85
|
+
readonly suffix?: string;
|
|
86
|
+
};
|
|
87
|
+
/** A new, empty, private folder, and its path. */
|
|
88
|
+
export declare function makeTempDir(options?: MakeTempOptions): Promise<string>;
|
|
89
|
+
/** A new, empty, private folder, without waiting. */
|
|
90
|
+
export declare function makeTempDirSync(options?: MakeTempOptions): string;
|
|
91
|
+
/** A new, empty, private file, and its path. */
|
|
92
|
+
export declare function makeTempFile(options?: MakeTempOptions): Promise<string>;
|
|
93
|
+
/** A file or folder moved to a new path, replacing a file there. */
|
|
94
|
+
export declare function rename(from: PathLike, to: PathLike): Promise<void>;
|
|
95
|
+
/** The same, without waiting. */
|
|
96
|
+
export declare function renameSync(from: PathLike, to: PathLike): void;
|
|
97
|
+
/** A file's bytes copied to a new path, replacing a file there. */
|
|
98
|
+
export declare function copyFile(from: PathLike, to: PathLike): Promise<void>;
|
|
99
|
+
/** A file's mode changed (ignored on Windows, which has none). */
|
|
100
|
+
export declare function chmod(path: PathLike, mode: number): Promise<void>;
|
|
101
|
+
/** A second name, `to`, for the file at `from` (a hard link), refused with `AlreadyExists` where `to` is taken: a file put in place whole, or not at all. */
|
|
102
|
+
export declare function link(from: PathLike, to: PathLike): Promise<void>;
|
|
103
|
+
/**
|
|
104
|
+
* A link at `path` that points at `target`; `type` matters on Windows only. `junction` (a folder, FR-073) is the Windows link any account
|
|
105
|
+
* may make (a symbolic link needs administrator rights or Developer Mode there): its target is made absolute, as Windows requires; on
|
|
106
|
+
* Linux and macOS it is an ordinary symbolic link.
|
|
107
|
+
*/
|
|
108
|
+
export declare function symlink(target: PathLike, path: PathLike, options?: {
|
|
109
|
+
readonly type?: "file" | "dir" | "junction";
|
|
110
|
+
}): Promise<void>;
|
|
111
|
+
/** Where a link points, as it was written. */
|
|
112
|
+
export declare function readLink(path: PathLike): Promise<string>;
|
|
113
|
+
/** The absolute path with every link followed. */
|
|
114
|
+
export declare function realPath(path: PathLike): Promise<string>;
|
|
115
|
+
/** A file cut (or extended with zeros) to `length` bytes, 0 by default. */
|
|
116
|
+
export declare function truncate(path: PathLike, length?: number): Promise<void>;
|
|
117
|
+
/** A file's access and modification times set. */
|
|
118
|
+
export declare function utime(path: PathLike, atime: Date | number, mtime: Date | number): Promise<void>;
|
|
119
|
+
/** Whether something is at `path` (a file, folder or link; a broken link counts). An error other than `NotFound` is thrown. */
|
|
120
|
+
export declare function exists(path: PathLike): Promise<boolean>;
|
|
121
|
+
/** The same, without waiting. */
|
|
122
|
+
export declare function existsSync(path: PathLike): boolean;
|
|
123
|
+
/** A text file's content, or `fallback` (undefined unless given) where nothing is there. Other errors are thrown. */
|
|
124
|
+
export declare function readTextOr<F extends string | undefined = undefined>(path: PathLike, fallback?: F): Promise<string | F>;
|
|
125
|
+
/** A folder and its parents made, where missing. */
|
|
126
|
+
export declare function ensureDir(path: PathLike): Promise<void>;
|
|
127
|
+
/**
|
|
128
|
+
* A text file written only where its content changed, in one step (a file beside it renamed over it, so a reader never sees half of it),
|
|
129
|
+
* its folder made where missing. Whether it was written.
|
|
130
|
+
*/
|
|
131
|
+
export declare function writeIfChanged(path: PathLike, content: string): Promise<boolean>;
|
|
132
|
+
/** The names of the folders directly in `path`, sorted; none where it does not exist. */
|
|
133
|
+
export declare function listDirs(path: PathLike): Promise<string[]>;
|
|
134
|
+
/** The names of the files directly in `path` that end in `suffix`, sorted; none where it does not exist. */
|
|
135
|
+
export declare function listFiles(path: PathLike, suffix?: string): Promise<string[]>;
|
|
136
|
+
/** Every file under a folder (links included, not followed), by its path relative to it with `/` between parts, sorted; none where it does not exist. */
|
|
137
|
+
export declare function walkFiles(root: PathLike, rel?: string): Promise<string[]>;
|
|
138
|
+
/** The SHA-256 of a file, read as a stream so a large file is not held in memory. */
|
|
139
|
+
export declare function sha256File(path: PathLike): Promise<Sha256>;
|
|
140
|
+
/** A temporary folder for the length of `f`, removed with everything in it afterwards, whatever `f` does. */
|
|
141
|
+
export declare function withTempDir<T>(f: (dir: string) => Promise<T>, options?: MakeTempOptions): Promise<T>;
|
|
142
|
+
/** A file's owner and group changed; `null` keeps one as it is. Ignored on Windows, which has no POSIX owners (FR-018). */
|
|
143
|
+
export declare function chown(path: PathLike, uid: number | null, gid: number | null): Promise<void>;
|
|
144
|
+
/** A link at `path` that points at `target`, without waiting; `type` matters on Windows only (`junction`: see `symlink`). */
|
|
145
|
+
export declare function symlinkSync(target: PathLike, path: PathLike, options?: {
|
|
146
|
+
readonly type?: "file" | "dir" | "junction";
|
|
147
|
+
}): void;
|
|
148
|
+
/** How to open a file, by these names: `read` alone where none is given. `append` writes at the end and implies `write`. */
|
|
149
|
+
export type OpenOptions = {
|
|
150
|
+
readonly read?: boolean;
|
|
151
|
+
readonly write?: boolean;
|
|
152
|
+
readonly append?: boolean;
|
|
153
|
+
readonly truncate?: boolean;
|
|
154
|
+
readonly create?: boolean;
|
|
155
|
+
readonly createNew?: boolean;
|
|
156
|
+
readonly mode?: number;
|
|
157
|
+
};
|
|
158
|
+
/** Where `seek` counts from: the start of the file, the handle's position, or the end (`start`, `current`, `end`). */
|
|
159
|
+
export type SeekWhence = "start" | "current" | "end";
|
|
160
|
+
/**
|
|
161
|
+
* An open file: it reads and writes at its position (a handle opened with `append` always writes at the end), `seek`s,
|
|
162
|
+
* `truncate`s, `stat`s and `sync`s, gives its bytes as a web `ReadableStream` and takes them as a `WritableStream` (each closes the file
|
|
163
|
+
* when it ends), and is closed by `close`, `using` or `await using`. It has no lock: one run at a time is `./lock.ts` (FR-039, FR-049).
|
|
164
|
+
* Made by {@link open} and {@link openSync}.
|
|
165
|
+
*/
|
|
166
|
+
export declare class FsFile implements Disposable, AsyncDisposable {
|
|
167
|
+
#private;
|
|
168
|
+
/** A handle over an open descriptor; use {@link open} or {@link openSync}. */
|
|
169
|
+
constructor(fd: number, path: string, append: boolean);
|
|
170
|
+
/** Bytes read into `buffer` from the position, which moves past them: how many, or `null` at the end of the file. */
|
|
171
|
+
read(buffer: Uint8Array): Promise<number | null>;
|
|
172
|
+
/** The same, without waiting. */
|
|
173
|
+
readSync(buffer: Uint8Array): number | null;
|
|
174
|
+
/** Bytes written at the position (at the end with `append`), which moves past them: how many, which may be fewer than given. */
|
|
175
|
+
write(data: Uint8Array): Promise<number>;
|
|
176
|
+
/** The same, without waiting. */
|
|
177
|
+
writeSync(data: Uint8Array): number;
|
|
178
|
+
/** The position moved by `offset` from the start, the position or the end; the new position, from the start. */
|
|
179
|
+
seek(offset: number, whence?: SeekWhence): Promise<number>;
|
|
180
|
+
/** The same, without waiting. */
|
|
181
|
+
seekSync(offset: number, whence?: SeekWhence): number;
|
|
182
|
+
/** The file cut (or extended with zeros) to `length` bytes, 0 by default; the position is kept. */
|
|
183
|
+
truncate(length?: number): Promise<void>;
|
|
184
|
+
/** The same, without waiting. */
|
|
185
|
+
truncateSync(length?: number): void;
|
|
186
|
+
/** What the open file is. */
|
|
187
|
+
stat(): Promise<FileInfo>;
|
|
188
|
+
/** The same, without waiting. */
|
|
189
|
+
statSync(): FileInfo;
|
|
190
|
+
/** The file's data and metadata written through to the disk. */
|
|
191
|
+
sync(): Promise<void>;
|
|
192
|
+
/** The same, without waiting. */
|
|
193
|
+
syncSync(): void;
|
|
194
|
+
/** The file's bytes from the position to the end, as a stream that closes the file when it ends or is cancelled. */
|
|
195
|
+
get readable(): ReadableStream<Uint8Array>;
|
|
196
|
+
/** A stream whose chunks are written whole at the position, closing the file when it is closed or aborted. */
|
|
197
|
+
get writable(): WritableStream<Uint8Array>;
|
|
198
|
+
/** The file closed; closing it again does nothing. */
|
|
199
|
+
close(): void;
|
|
200
|
+
/** Closed at the end of a `using` block. */
|
|
201
|
+
[Symbol.dispose](): void;
|
|
202
|
+
/** Closed at the end of an `await using` block. */
|
|
203
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
204
|
+
}
|
|
205
|
+
/** A file opened for reading where no options are given. `AlreadyExists` with `createNew`, `NotFound` without `create`. */
|
|
206
|
+
export declare function open(path: PathLike, options?: OpenOptions): Promise<FsFile>;
|
|
207
|
+
/** The same, without waiting. */
|
|
208
|
+
export declare function openSync(path: PathLike, options?: OpenOptions): FsFile;
|
|
209
|
+
/** How to copy: replace what is at the destination (`overwrite`), keep the access and modification times (`preserveTimestamps`). */
|
|
210
|
+
export type CopyOptions = {
|
|
211
|
+
readonly overwrite?: boolean;
|
|
212
|
+
readonly preserveTimestamps?: boolean;
|
|
213
|
+
};
|
|
214
|
+
/**
|
|
215
|
+
* A file, a link or a folder with everything in it copied, as `@std/fs`'s `copy` does: a link is copied as a link, modes are kept (not on
|
|
216
|
+
* Windows, FR-018), and what is at the destination is `AlreadyExists` unless `overwrite`. A folder cannot be copied into itself.
|
|
217
|
+
*/
|
|
218
|
+
export declare function copy(from: PathLike, to: PathLike, options?: CopyOptions): Promise<void>;
|
|
219
|
+
/** One entry of a walk: what `readDir` gives, with its path (the root's joined with the names, by the platform's separator). */
|
|
220
|
+
export type WalkEntry = DirEntry & {
|
|
221
|
+
readonly path: string;
|
|
222
|
+
};
|
|
223
|
+
/**
|
|
224
|
+
* What a walk gives, as `@std/fs`'s `walk` takes it: how deep (`maxDepth`, the root being 0), which kinds (`includeFiles`, `includeDirs`,
|
|
225
|
+
* `includeSymlinks`, all true by default), whether links are followed (`followSymlinks`, false) and then given by their real path
|
|
226
|
+
* (`canonicalize`, true), and which paths: ending in one of `exts`, matching one of `match`, matching none of `skip`. The expressions are
|
|
227
|
+
* tested against the path with `/` between its parts on every platform, so one expression serves Windows too.
|
|
228
|
+
*/
|
|
229
|
+
export type WalkOptions = {
|
|
230
|
+
readonly maxDepth?: number;
|
|
231
|
+
readonly includeFiles?: boolean;
|
|
232
|
+
readonly includeDirs?: boolean;
|
|
233
|
+
readonly includeSymlinks?: boolean;
|
|
234
|
+
readonly followSymlinks?: boolean;
|
|
235
|
+
readonly canonicalize?: boolean;
|
|
236
|
+
readonly exts?: readonly string[];
|
|
237
|
+
readonly match?: readonly RegExp[];
|
|
238
|
+
readonly skip?: readonly RegExp[];
|
|
239
|
+
};
|
|
240
|
+
/**
|
|
241
|
+
* Every entry under a folder, as `@std/fs`'s `walk` gives them (see {@link WalkOptions}), depth first and in the byte order of the names at
|
|
242
|
+
* each level, so a walk is the same every time; the root first, where folders are included; a file as the root is the walk's one entry.
|
|
243
|
+
* `NotFound` where the root is not there.
|
|
244
|
+
*/
|
|
245
|
+
export declare function walk(root: PathLike, options?: WalkOptions): AsyncGenerator<WalkEntry>;
|
|
246
|
+
/**
|
|
247
|
+
* How `expandGlob` reads its glob: the folder it is relative to (`root`, the working folder by default), globs whose matches (and all under
|
|
248
|
+
* them) are left out (`exclude`), whether folders are given (`includeDirs`, true) and links followed (`followSymlinks`, false), and the
|
|
249
|
+
* glob's own options (`extended`, `globstar`, `caseInsensitive`).
|
|
250
|
+
*/
|
|
251
|
+
export type ExpandGlobOptions = GlobOptions & {
|
|
252
|
+
readonly root?: PathLike;
|
|
253
|
+
readonly exclude?: readonly string[];
|
|
254
|
+
readonly includeDirs?: boolean;
|
|
255
|
+
readonly followSymlinks?: boolean;
|
|
256
|
+
};
|
|
257
|
+
/**
|
|
258
|
+
* The entries a glob matches (`src/**\/*.ts`; see `../kernel/glob.ts`), as `@std/fs`'s `expandGlob` gives them, sorted in the byte order of
|
|
259
|
+
* their paths so the result is the same every time. A glob is written with `/`, also on Windows, and may be absolute (`/srv/*.log`,
|
|
260
|
+
* `C:/x/*`); a relative one is read from `root`. Entries are matched by their path relative to where the glob starts. A glob that begins
|
|
261
|
+
* with `!` is refused as `InvalidData`; a folder that is not there has no entries.
|
|
262
|
+
*/
|
|
263
|
+
export declare function expandGlob(glob: string, options?: ExpandGlobOptions): AsyncGenerator<WalkEntry>;
|