@zukhruf/fs 0.0.0-stage → 0.3.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# @zukhruf/fs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Helpers that write files, and a lock on a file that the kernel frees when its holder dies. A reader never sees a part of a write. `@zukhruf/mutex` uses them for its lock files, `@zukhruf/fencing` for its fencing counters, and `@zukhruf/election` for the claim and the epoch of each election. `@zukhruf/single-flight` keeps no lock files of its own: its election claims a `FileLock` through `@zukhruf/election`.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Replace a file in one step
+
+A write that changes a file in place can stop halfway. Then a reader sees a part of the old content and a part of the new content. `atomicWrite` fills a draft beside the path, and then moves the draft over the path with one rename. A reader sees the old content or the new content.
+
+```ts
+import { atomicWrite } from '@zukhruf/fs';
+
+await atomicWrite('/var/lib/app/queue', 'first\nsecond\n');
+```
+
+## Make the replacement durable
+
+After a rename, the operating system can keep the new content in memory for some time. A power loss in that time can bring back the old content. `durableWrite` replaces the file in one step, like `atomicWrite`. It returns only after the new content and the rename are on the disk:
+
+1. It writes the draft and syncs the draft to the disk.
+2. It moves the draft over the path.
+3. It syncs the directory, because the rename is a change of the directory.
+
+```ts
+import { durableWrite } from '@zukhruf/fs';
+
+await durableWrite('/var/lib/app/counter', '42');
+```
+
+Use `durableWrite` when a value must never go back after a crash, for example a counter that gives out fencing tokens. A counter that goes back gives the same token two times.
+
+On Windows, a process cannot open a directory to sync it. Some file systems refuse a sync of a directory with `EINVAL` or `ENOTSUP`. In these cases, the rename is as durable as that system makes it. Each other error of the sync reaches the caller.
+
+## Create a file only when it is absent
+
+`createExclusive` creates the file when no file is at the path, and returns `true`. When a file is there, it changes nothing and returns `false`. It fills a draft first and then links the draft to the path. Thus the file is never empty: a reader of the new file sees all of its content.
+
+```ts
+import { createExclusive } from '@zukhruf/fs';
+
+const created = await createExclusive('/var/lib/app/job.lock', 'pid 4242');
+if (!created) console.log('Another process holds the job.');
+```
+
+## A failed write leaves no draft
+
+When a write fails, it removes its draft. Thus failed writes do not fill the directory with drafts. The file at the path keeps its old content.
+
+## Keep room for the name of the draft
+
+A draft has the name of the path plus `draftSuffixLength` characters. Most file systems limit a file name to 255 bytes. A caller that makes long file names, for example from user keys, keeps `draftSuffixLength` characters of room. Otherwise the name of the draft is too long, and the write fails with `ENAMETOOLONG`.
+
+## Name a file after any key
+
+A caller can keep one file for each key, for example one lock file for each lock key. The caller must make a file name from the key. A key can hold `/`, be `.` or `..`, or be too long for a file name. `safeFileName(key, longestSuffix)` gives a name that is one path segment. The name plus `longestSuffix` more characters fits in 255 characters, the longest file name of most file systems.
+
+```ts
+import { join } from 'node:path';
+
+import { createExclusive, draftSuffixLength, safeFileName } from '@zukhruf/fs';
+
+const name = safeFileName('orders/2026', '.lock'.length + draftSuffixLength);
+await createExclusive(join('/var/lib/app/locks', `${name}.lock`), 'pid 4242');
+// The file is orders%2F2026.lock
+```
+
+- A key that fits gets its URI encoding, with each `.` as `%2E`. Thus a name is never `.` or `..`. The name of `job.lock` is `job%2Elock`, so it is never the name of `job` plus the suffix `.lock`.
+- A key that does not fit, or that is not well-formed Unicode, gets a hashed name: the first 32 characters of its encoding, `%%`, and the SHA-256 of its UTF-16 code units in hex. A hashed name has at most 98 characters. An encoding never holds `%%`, so a hashed name is never the name of a key that fits.
+- The rule does not change between versions. Processes of two versions find the same file for a key.
+- On a case-insensitive file system, keys that differ only by case get one file.
+
+## Try again while Windows refuses a file for a moment
+
+Windows refuses a file for a moment while a delete of it is in progress, or while another program holds it open with no sharing, for example a virus scanner. The error codes are `EPERM`, `EACCES`, and `EBUSY`. A real permission error has the same codes. `patiently` runs an operation again while Windows refuses the file, for up to 1 second. After that, the error reaches the caller. On other systems, `patiently` runs the operation one time.
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+import { patiently } from '@zukhruf/fs';
+
+const content = await patiently(() =>
+  readFile('/var/lib/app/job.lock', 'utf8'),
+);
+```
+
+Each write of this package uses `patiently` for its rename or link.
+
+## Lock a file
+
+A process can die while it holds a lock. When the lock is a file that is present, for example a file from `createExclusive`, the file stays after the process dies. Then the lock stays until somebody deletes the file. A `FileLock` is a lock that the kernel holds. When the process of the holder stops, however it stops, the kernel frees the lock at once.
+
+Node.js has no `flock`. Thus a `FileLock` is an exclusive SQLite transaction on the file. SQLite is part of Node.js (`node:sqlite`), so this package has no dependencies.
+
+```ts
+import { FileLock } from '@zukhruf/fs';
+
+using lock = FileLock.open('/var/lib/app/job.lock');
+if (lock.tryLock()) {
+  try {
+    await runJob();
+  } finally {
+    lock.unlock();
+  }
+} else {
+  console.log('Another process holds the job.');
+}
+```
+
+- `FileLock.open(path)` opens the file. When no file is at the path, it creates an empty file. It takes no lock.
+- `tryLock()` takes the lock and returns `true`. When another handle holds the lock, it returns `false` at once. It never waits: to wait, try again after a pause. Two handles in one process exclude each other too.
+- When the file has other content, `tryLock()` throws. Only an empty file or a SQLite database can be a file lock.
+- `unlock()` lets the lock go. The handle stays open, and it can lock again.
+- A disposal closes the handle. A lock that the handle holds goes with it. A second disposal does nothing.
+- A held lock stays held when nothing refers to its handle any more. Only `unlock()`, a disposal, or the end of the process lets it go.
+
+`FileLock.check(path)` tells if a handle holds the lock now. It returns `'locked'`, `'unlocked'`, or `'missing'` when no file is at the path. It reads the file one time and never creates it. For that read, it holds a shared lock for a moment, so a `tryLock()` at that moment can return `false`. The answer can be old when you use it. Other faults, for example a directory at the path, throw.
+
+Obey these rules:
+
+- Open the file only through `FileLock`. On Unix, the lock is a POSIX record lock of the process. When the process closes any other descriptor of the file, the kernel drops the lock and gives no error.
+- Do not delete the file while processes use it. A new file at the path has no lock, so a second process can lock it while the first one holds the old file.
+- Use `assertLocalDirectory` first. Other machines do not see the lock reliably on a network file system.
+
+The journal of the transaction is in memory, so a holder that dies leaves no `<path>-journal` file. Other programs can hold an exclusive SQLite transaction on the same file in the default journal mode. Such a transaction and a `FileLock` exclude each other. A journal file that such a program leaves is deleted by the next `tryLock()`.
+
+## Refuse a network directory
+
+A lock that a file or SQLite holds works between the processes of one machine. On a network file system, for example NFS or SMB, other machines do not see that lock reliably. `assertLocalDirectory(directory)` rejects with `NetworkDirectoryError` when the directory is on a network file system. A directory that does not exist yet gets the result of its nearest parent that exists.
+
+```ts
+import { NetworkDirectoryError, assertLocalDirectory } from '@zukhruf/fs';
+
+try {
+  await assertLocalDirectory('/mnt/shared/locks');
+} catch (error) {
+  if (error instanceof NetworkDirectoryError) console.log(error.fileSystem); // 'NFS'
+  throw error;
+}
+```
+
+- On Linux, the check reads the file system type with `statfs`. FUSE counts as local.
+- On Windows, a UNC path, for example `\\server\share`, is a network directory.
+- On macOS, each directory counts as local, because macOS gives no stable file system type.
+- When `statfs` fails, the check does not reject. The directory is used as if the check did not exist.
+
+`@zukhruf/mutex` and `@zukhruf/single-flight` give this same `NetworkDirectoryError` class. A catch with `instanceof` works for each of them.
+
+## Check the error code
+
+`isErrno(error, code)` tells if `error` is a Node.js system error with that error code.
+
+```ts
+import { isErrno } from '@zukhruf/fs';
+
+try {
+  await readFile(path, 'utf8');
+} catch (error) {
+  if (!isErrno(error, 'ENOENT')) throw error;
+}
+```

package/dist/atomic-write.d.ts

@@ -0,0 +1,3 @@
+/** Replaces `path` in one step, so readers see the old or the new content, never a partial write. */
+export declare function atomicWrite(path: string, content: string): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAKA,qGAAqG;AACrG,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAU9D"}

package/dist/atomic-write.js

@@ -0,0 +1,17 @@
+import { rm, writeFile } from 'node:fs/promises';
+import { draftOf } from "./draft.js";
+import { replaceFile } from "./replace-file.js";
+/** Replaces `path` in one step, so readers see the old or the new content, never a partial write. */
+export async function atomicWrite(path, content) {
+    const draft = draftOf(path);
+    try {
+        await writeFile(draft, content);
+        await replaceFile(draft, path);
+    }
+    catch (error) {
+        // A draft that never replaced `path` would only pile up, one per failed write.
+        await rm(draft, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,qGAAqG;AACrG,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,OAAe;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/create-exclusive.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates `path` holding `content` unless it already exists. Linking a fully
+ * written file makes creation atomic, so the file is never seen empty.
+ */
+export declare function createExclusive(path: string, content: string): Promise<boolean>;
+//# sourceMappingURL=create-exclusive.d.ts.map

package/dist/create-exclusive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-exclusive.d.ts","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,oBAYlE"}

package/dist/create-exclusive.js

@@ -0,0 +1,29 @@
+import { link, unlink, writeFile } from 'node:fs/promises';
+import { draftOf } from "./draft.js";
+import { isErrno } from "./errno.js";
+import { patiently } from "./patiently.js";
+/**
+ * Creates `path` holding `content` unless it already exists. Linking a fully
+ * written file makes creation atomic, so the file is never seen empty.
+ */
+export async function createExclusive(path, content) {
+    const draft = draftOf(path);
+    await writeFile(draft, content);
+    try {
+        await patiently(() => link(draft, path));
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, 'EEXIST'))
+            return false;
+        throw error;
+    }
+    finally {
+        await removeDraft(draft);
+    }
+}
+/** A draft left behind has a unique name, so it never blocks a key; failing to remove it must not change whether `path` was created. */
+async function removeDraft(draft) {
+    await patiently(() => unlink(draft)).catch(() => { });
+}
+//# sourceMappingURL=create-exclusive.js.map

package/dist/create-exclusive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-exclusive.js","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,OAAe;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,wIAAwI;AACxI,KAAK,UAAU,WAAW,CAAC,KAAa;IACtC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/draft.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A write fills a draft beside `path` and then puts it in place in one step,
+ * so a reader sees the old content or the new content, never a part of it.
+ * The random name keeps two writers of one path apart.
+ */
+export declare const draftOf: (path: string) => string;
+/**
+ * The length of what a write adds to a path to name its draft. A caller that
+ * makes long file names keeps this much room, or the draft's name is too long
+ * for the file system.
+ */
+export declare const draftSuffixLength: number;
+//# sourceMappingURL=draft.d.ts.map

package/dist/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,WAAkC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAqB,CAAC"}

package/dist/draft.js

@@ -0,0 +1,14 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * A write fills a draft beside `path` and then puts it in place in one step,
+ * so a reader sees the old content or the new content, never a part of it.
+ * The random name keeps two writers of one path apart.
+ */
+export const draftOf = (path) => `${path}.${randomUUID()}.tmp`;
+/**
+ * The length of what a write adds to a path to name its draft. A caller that
+ * makes long file names keeps this much room, or the draft's name is too long
+ * for the file system.
+ */
+export const draftSuffixLength = draftOf('').length;
+//# sourceMappingURL=draft.js.map

package/dist/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;AAEvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC"}

package/dist/durable-write.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Replaces `path` in one step like `atomicWrite`, and returns only once both
+ * the new content and the replacement survive a power loss: a counter that
+ * goes back after a crash would hand out a token twice.
+ */
+export declare function durableWrite(path: string, content: string): Promise<void>;
+//# sourceMappingURL=durable-write.d.ts.map

package/dist/durable-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-write.d.ts","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAW/D"}

package/dist/durable-write.js

@@ -0,0 +1,46 @@
+import { open, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { draftOf } from "./draft.js";
+import { isErrno } from "./errno.js";
+import { replaceFile } from "./replace-file.js";
+/**
+ * Replaces `path` in one step like `atomicWrite`, and returns only once both
+ * the new content and the replacement survive a power loss: a counter that
+ * goes back after a crash would hand out a token twice.
+ */
+export async function durableWrite(path, content) {
+    const draft = draftOf(path);
+    try {
+        await writeSynced(draft, content);
+        await replaceFile(draft, path);
+    }
+    catch (error) {
+        // A draft that never replaced `path` would only pile up, one per failed write.
+        await rm(draft, { force: true });
+        throw error;
+    }
+    await syncDirectory(dirname(path));
+}
+async function writeSynced(path, content) {
+    await using handle = await open(path, 'wx');
+    await handle.writeFile(content);
+    await handle.sync();
+}
+/**
+ * A rename lives in its directory, so the directory must reach the disk too.
+ * Windows cannot open a directory to sync it, and some file systems refuse to
+ * sync one; there the rename is as durable as that system makes it.
+ */
+async function syncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    await using handle = await open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isErrno(error, 'EINVAL') && !isErrno(error, 'ENOTSUP'))
+            throw error;
+    }
+}
+//# sourceMappingURL=durable-write.js.map

package/dist/durable-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-write.js","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe;IAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,OAAe;IACtD,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC5C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IACzC,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC;YAAE,MAAM,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC"}

package/dist/errno.d.ts

@@ -0,0 +1,2 @@
+export declare function isErrno(error: unknown, code: string): boolean;
+//# sourceMappingURL=errno.d.ts.map

package/dist/errno.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno.d.ts","sourceRoot":"","sources":["../src/errno.ts"],"names":[],"mappings":"AAAA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/errno.js

@@ -0,0 +1,4 @@
+export function isErrno(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+//# sourceMappingURL=errno.js.map

package/dist/errno.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno.js","sourceRoot":"","sources":["../src/errno.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,OAAO,CAAC,KAAc,EAAE,IAAY;IAClD,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC1E,CAAC"}

package/dist/file-lock.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A lock on a file that the kernel holds: an exclusive SQLite transaction on
+ * the file. The kernel frees it when the holder's process dies, however it
+ * dies, so a crash never leaves the file locked.
+ *
+ * On Unix the lock is a POSIX record lock, which the kernel ties to the
+ * process and the file. Closing any other descriptor of the file in this
+ * process drops the lock without a word, so open the file only through
+ * `FileLock`. A network file system does not share the lock reliably between
+ * machines: check the directory with `assertLocalDirectory` first.
+ */
+export declare class FileLock implements Disposable {
+    #private;
+    private constructor();
+    /** Opens the file, and creates it empty when it is absent. Takes no lock. */
+    static open(path: string): FileLock;
+    /**
+     * Whether a handle holds the lock on the file at `path` now. It reads
+     * the file once, read-only, and never creates it. For that read it takes a
+     * shared lock, so a `tryLock` at that moment can return `false`. The answer
+     * can be stale as soon as it returns.
+     */
+    static check(path: string): 'locked' | 'unlocked' | 'missing';
+    /** Takes the lock without waiting. Returns `false` when another handle holds it. */
+    tryLock(): boolean;
+    /** Lets the lock go. The handle stays open for the next `tryLock`. */
+    unlock(): void;
+    /** Closes the handle. A lock that it holds goes with it. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,YAAW,UAAU;;IAIzC,OAAO;IAKP,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAMnC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS;IAsB7D,oFAAoF;IACpF,OAAO,IAAI,OAAO;IAmBlB,sEAAsE;IACtE,MAAM,IAAI,IAAI;IAUd,4DAA4D;IAC5D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAIzB"}

package/dist/file-lock.js

@@ -0,0 +1,102 @@
+import { existsSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+const SQLITE_BUSY = 5;
+const SQLITE_CANTOPEN = 14;
+/** Garbage collection closes a connection that nobody references, and a lock that it holds goes with it. */
+const held = new Set();
+/**
+ * A lock on a file that the kernel holds: an exclusive SQLite transaction on
+ * the file. The kernel frees it when the holder's process dies, however it
+ * dies, so a crash never leaves the file locked.
+ *
+ * On Unix the lock is a POSIX record lock, which the kernel ties to the
+ * process and the file. Closing any other descriptor of the file in this
+ * process drops the lock without a word, so open the file only through
+ * `FileLock`. A network file system does not share the lock reliably between
+ * machines: check the directory with `assertLocalDirectory` first.
+ */
+export class FileLock {
+    #path;
+    #database;
+    constructor(path, database) {
+        this.#path = path;
+        this.#database = database;
+    }
+    /** Opens the file, and creates it empty when it is absent. Takes no lock. */
+    static open(path) {
+        // No busy timeout (Node's default is 0): one above zero blocks the event
+        // loop while it waits, so a caller tries again instead.
+        return new FileLock(path, new DatabaseSync(path));
+    }
+    /**
+     * Whether a handle holds the lock on the file at `path` now. It reads
+     * the file once, read-only, and never creates it. For that read it takes a
+     * shared lock, so a `tryLock` at that moment can return `false`. The answer
+     * can be stale as soon as it returns.
+     */
+    static check(path) {
+        let database;
+        try {
+            database = new DatabaseSync(path, { readOnly: true });
+        }
+        catch (error) {
+            // A file that exists but cannot be opened is a fault, not a missing file.
+            if (hasResultCode(error, SQLITE_CANTOPEN) && !existsSync(path)) {
+                return 'missing';
+            }
+            throw error;
+        }
+        try {
+            database.prepare('SELECT count(*) FROM sqlite_schema').get();
+            return 'unlocked';
+        }
+        catch (error) {
+            if (hasResultCode(error, SQLITE_BUSY))
+                return 'locked';
+            throw error;
+        }
+        finally {
+            database.close();
+        }
+    }
+    /** Takes the lock without waiting. Returns `false` when another handle holds it. */
+    tryLock() {
+        if (this.#database.isTransaction) {
+            throw new Error(`This handle holds the file lock ${JSON.stringify(this.#path)} already.`);
+        }
+        try {
+            // A journal on disk would outlive a holder that dies. The statement is
+            // busy too while another handle holds the lock, so each try runs it.
+            this.#database.exec('PRAGMA journal_mode = MEMORY');
+            this.#database.exec('BEGIN EXCLUSIVE');
+        }
+        catch (error) {
+            if (hasResultCode(error, SQLITE_BUSY))
+                return false;
+            throw error;
+        }
+        held.add(this.#database);
+        return true;
+    }
+    /** Lets the lock go. The handle stays open for the next `tryLock`. */
+    unlock() {
+        if (!this.#database.isTransaction) {
+            throw new Error(`This handle does not hold the file lock ${JSON.stringify(this.#path)}.`);
+        }
+        this.#database.exec('ROLLBACK');
+        held.delete(this.#database);
+    }
+    /** Closes the handle. A lock that it holds goes with it. */
+    [Symbol.dispose]() {
+        held.delete(this.#database);
+        this.#database[Symbol.dispose]();
+    }
+}
+/** The low byte of SQLite's extended result code is the primary code, so this covers each variant of `code`. */
+function hasResultCode(error, code) {
+    return (error instanceof Error &&
+        'errcode' in error &&
+        typeof error.errcode === 'number' &&
+        (error.errcode & 0xff) === code);
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/file-lock.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { atomicWrite } from './atomic-write.ts';
+export { createExclusive } from './create-exclusive.ts';
+export { draftSuffixLength } from './draft.ts';
+export { durableWrite } from './durable-write.ts';
+export { isErrno } from './errno.ts';
+export { FileLock } from './file-lock.ts';
+export { assertLocalDirectory } from './local-directory.ts';
+export { NetworkDirectoryError } from './network-directory-error.ts';
+export { patiently } from './patiently.ts';
+export { safeFileName } from './safe-file-name.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { atomicWrite } from "./atomic-write.js";
+export { createExclusive } from "./create-exclusive.js";
+export { draftSuffixLength } from "./draft.js";
+export { durableWrite } from "./durable-write.js";
+export { isErrno } from "./errno.js";
+export { FileLock } from "./file-lock.js";
+export { assertLocalDirectory } from "./local-directory.js";
+export { NetworkDirectoryError } from "./network-directory-error.js";
+export { patiently } from "./patiently.js";
+export { safeFileName } from "./safe-file-name.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/local-directory.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rejects with `NetworkDirectoryError` when `directory` is on a network file
+ * system, where file locks are not shared reliably between machines.
+ * A directory that does not exist yet is judged by its nearest existing parent.
+ */
+export declare function assertLocalDirectory(directory: string): Promise<void>;
+//# sourceMappingURL=local-directory.d.ts.map

package/dist/local-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-directory.d.ts","sourceRoot":"","sources":["../src/local-directory.ts"],"names":[],"mappings":"AA+DA;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E"}

package/dist/local-directory.js

@@ -0,0 +1,75 @@
+import { statfs } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isErrno } from "./errno.js";
+import { NetworkDirectoryError } from "./network-directory-error.js";
+/**
+ * The `f_type` Linux's statfs reports for each network file system: from the
+ * kernel's uapi/linux/magic.h, gfs2_ondisk.h (GFS2) and Lustre's lustre_user.h.
+ * FUSE is left out on purpose: on one kernel, its mounts hold file locks.
+ */
+const linuxNetworkFileSystems = new Map([
+    [0x6969n, 'NFS'],
+    [0x517bn, 'SMB'],
+    [0xff534d42n, 'CIFS'],
+    [0xfe534d42n, 'SMB2'],
+    [0x00c36400n, 'Ceph'],
+    [0x5346414fn, 'AFS'],
+    [0x6b414653n, 'kAFS'],
+    [0x73757245n, 'Coda'],
+    [0x564cn, 'NCP'],
+    [0x7461636fn, 'OCFS2'],
+    [0x01161970n, 'GFS2'],
+    [0x0bd00bd0n, 'Lustre'],
+    [0x01021997n, '9p'],
+]);
+const local = { kind: 'local' };
+const unknown = { kind: 'unknown' };
+/**
+ * How each platform judges a directory. Only Linux reports a stable file
+ * system type; macOS numbers its file systems as they load, so it has no
+ * judge, and every directory counts as local there.
+ */
+const judges = {
+    linux: (path) => statfsOfNearest(path).then(({ type }) => {
+        // f_type is a signed long, so a magic with its high bit set can arrive sign-extended.
+        const fileSystem = linuxNetworkFileSystems.get(BigInt.asUintN(32, type));
+        return fileSystem ? { kind: 'network', fileSystem } : local;
+    }, () => unknown),
+    win32: async (path) => isUncPath(path) ? { kind: 'network', fileSystem: 'UNC share' } : local,
+};
+/** A directory's file system does not change under a running process, so each local one is judged once. */
+const localDirectories = new Set();
+/**
+ * Rejects with `NetworkDirectoryError` when `directory` is on a network file
+ * system, where file locks are not shared reliably between machines.
+ * A directory that does not exist yet is judged by its nearest existing parent.
+ */
+export async function assertLocalDirectory(directory) {
+    const path = resolve(directory);
+    if (localDirectories.has(path))
+        return;
+    const judgement = (await judges[process.platform]?.(path)) ?? local;
+    if (judgement.kind === 'network') {
+        throw new NetworkDirectoryError(directory, judgement.fileSystem);
+    }
+    if (judgement.kind === 'local')
+        localDirectories.add(path);
+}
+async function statfsOfNearest(path) {
+    try {
+        return await statfs(path, { bigint: true });
+    }
+    catch (error) {
+        const parent = dirname(path);
+        if (!isErrno(error, 'ENOENT') || parent === path)
+            throw error;
+        return statfsOfNearest(parent);
+    }
+}
+/** `\\server\share`, `\\?\UNC\server\share` and `\\.\UNC\server\share`; `\\?\C:\` names a local drive. */
+function isUncPath(path) {
+    if (/^\\\\[?.]\\/.test(path))
+        return /^\\\\[?.]\\UNC\\/i.test(path);
+    return path.startsWith('\\\\');
+}
+//# sourceMappingURL=local-directory.js.map

package/dist/local-directory.js.map

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

package/dist/network-directory-error.d.ts

@@ -0,0 +1,8 @@
+/** The directory is on a file system that other machines share, where file locks do not hold. */
+export declare class NetworkDirectoryError extends Error {
+    readonly directory: string;
+    /** The network file system the directory is on, for example `NFS`. */
+    readonly fileSystem: string;
+    constructor(directory: string, fileSystem: string);
+}
+//# sourceMappingURL=network-directory-error.d.ts.map

package/dist/network-directory-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-directory-error.d.ts","sourceRoot":"","sources":["../src/network-directory-error.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAQlD"}

package/dist/network-directory-error.js

@@ -0,0 +1,13 @@
+/** The directory is on a file system that other machines share, where file locks do not hold. */
+export class NetworkDirectoryError extends Error {
+    directory;
+    /** The network file system the directory is on, for example `NFS`. */
+    fileSystem;
+    constructor(directory, fileSystem) {
+        super(`The directory ${JSON.stringify(directory)} is on a network file system (${fileSystem}), where file locks are not shared reliably between machines. Use a local directory.`);
+        this.name = 'NetworkDirectoryError';
+        this.directory = directory;
+        this.fileSystem = fileSystem;
+    }
+}
+//# sourceMappingURL=network-directory-error.js.map

package/dist/network-directory-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-directory-error.js","sourceRoot":"","sources":["../src/network-directory-error.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,SAAS,CAAS;IAC3B,sEAAsE;IAC7D,UAAU,CAAS;IAE5B,YAAY,SAAiB,EAAE,UAAkB;QAC/C,KAAK,CACH,iBAAiB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,iCAAiC,UAAU,sFAAsF,CAC5K,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/patiently.d.ts

@@ -0,0 +1,3 @@
+/** Runs `operation`, and runs it again while Windows refuses the file for a moment; after that, the error reaches the caller. */
+export declare function patiently<T>(operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=patiently.d.ts.map

package/dist/patiently.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patiently.d.ts","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAoBA,iIAAiI;AACjI,wBAAsB,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc1E"}

package/dist/patiently.js

@@ -0,0 +1,30 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { isErrno } from "./errno.js";
+/** How long to retry a file operation that Windows refuses for a moment. */
+const WINDOWS_PATIENCE = 1000;
+/**
+ * Windows refuses a file for a moment while another program holds it open
+ * with no sharing, as a virus scanner can, or while a delete of it is in
+ * progress. The error code is the same as for a real permission denial, so a
+ * refusal is retried only for a limited time.
+ */
+function isRefusedForNow(error) {
+    return (process.platform === 'win32' &&
+        ['EPERM', 'EACCES', 'EBUSY'].some((code) => isErrno(error, code)));
+}
+/** Runs `operation`, and runs it again while Windows refuses the file for a moment; after that, the error reaches the caller. */
+export async function patiently(operation) {
+    const started = performance.now();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isRefusedForNow(error) ||
+                performance.now() - started > WINDOWS_PATIENCE)
+                throw error;
+            await delay(Math.min(5 * 2 ** attempt, 100));
+        }
+    }
+}
+//# sourceMappingURL=patiently.js.map

package/dist/patiently.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patiently.js","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,4EAA4E;AAC5E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC5B,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAClE,CAAC;AACJ,CAAC;AAED,iIAAiI;AACjI,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,SAA2B;IAC5D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,CAAC,eAAe,CAAC,KAAK,CAAC;gBACvB,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,gBAAgB;gBAE9C,MAAM,KAAK,CAAC;YACd,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/replace-file.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Moves `draft` over `path` in one step. On Windows, a rename over a file
+ * fails while another process has that file open, for example a waiter that
+ * reads it at that moment. The refusal is brief, so the rename is tried again;
+ * it stays the single commit point.
+ */
+export declare function replaceFile(draft: string, path: string): Promise<void>;
+//# sourceMappingURL=replace-file.d.ts.map

package/dist/replace-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,iBAEtD"}

package/dist/replace-file.js

@@ -0,0 +1,12 @@
+import { rename } from 'node:fs/promises';
+import { patiently } from "./patiently.js";
+/**
+ * Moves `draft` over `path` in one step. On Windows, a rename over a file
+ * fails while another process has that file open, for example a waiter that
+ * reads it at that moment. The refusal is brief, so the rename is tried again;
+ * it stays the single commit point.
+ */
+export function replaceFile(draft, path) {
+    return patiently(() => rename(draft, path));
+}
+//# sourceMappingURL=replace-file.js.map

package/dist/replace-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file.js","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY;IACrD,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/safe-file-name.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Maps any key to a single path segment that still fits a file name after the
+ * caller adds up to `longestSuffix` characters. Encoding every dot means a key
+ * can never be `.` or `..`, and suffixes such as `.lock` can never collide with
+ * a key. On a case-insensitive file system, keys that differ only by case share
+ * a name and so one file. A lock file then guards more keys than it must, but
+ * never fewer.
+ *
+ * A key whose encoding does not fit, or that is not well-formed Unicode and so
+ * has no encoding, gets the start of its encoding, `%%`, and the SHA-256 of its
+ * UTF-16 code units. A key that fits keeps the name earlier versions gave it, so
+ * processes of two versions share its file. No encoding contains `%%`, so the
+ * two kinds of name never meet; the digest is hex, whose one case cannot fold
+ * two digests into one name; and the code units keep lone surrogates apart.
+ */
+export declare function safeFileName(key: string, longestSuffix: number): string;
+//# sourceMappingURL=safe-file-name.d.ts.map

package/dist/safe-file-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-file-name.d.ts","sourceRoot":"","sources":["../src/safe-file-name.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAYvE"}

package/dist/safe-file-name.js

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+/** The longest file name that ext4, APFS, NTFS and tmpfs accept. */
+const longestFileName = 255;
+/** Enough of a long key's start to recognize it in a directory listing. */
+const visibleStart = 32;
+/**
+ * Maps any key to a single path segment that still fits a file name after the
+ * caller adds up to `longestSuffix` characters. Encoding every dot means a key
+ * can never be `.` or `..`, and suffixes such as `.lock` can never collide with
+ * a key. On a case-insensitive file system, keys that differ only by case share
+ * a name and so one file. A lock file then guards more keys than it must, but
+ * never fewer.
+ *
+ * A key whose encoding does not fit, or that is not well-formed Unicode and so
+ * has no encoding, gets the start of its encoding, `%%`, and the SHA-256 of its
+ * UTF-16 code units. A key that fits keeps the name earlier versions gave it, so
+ * processes of two versions share its file. No encoding contains `%%`, so the
+ * two kinds of name never meet; the digest is hex, whose one case cannot fold
+ * two digests into one name; and the code units keep lone surrogates apart.
+ */
+export function safeFileName(key, longestSuffix) {
+    if (key.isWellFormed()) {
+        const encoded = encode(key);
+        if (encoded.length + longestSuffix <= longestFileName)
+            return encoded;
+    }
+    const start = encode(key.toWellFormed())
+        .slice(0, visibleStart)
+        .replace(/%[0-9A-F]?$/, '');
+    const digest = createHash('sha256')
+        .update(Buffer.from(key, 'utf16le'))
+        .digest('hex');
+    return `${start}%%${digest}`;
+}
+function encode(key) {
+    return encodeURIComponent(key).replaceAll('.', '%2E');
+}
+//# sourceMappingURL=safe-file-name.js.map

package/dist/safe-file-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-file-name.js","sourceRoot":"","sources":["../src/safe-file-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,oEAAoE;AACpE,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,2EAA2E;AAC3E,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,aAAqB;IAC7D,IAAI,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,GAAG,aAAa,IAAI,eAAe;YAAE,OAAO,OAAO,CAAC;IACxE,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;SACrC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;SACtB,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;SAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;SACnC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,GAAG,KAAK,KAAK,MAAM,EAAE,CAAC;AAC/B,CAAC;AAED,SAAS,MAAM,CAAC,GAAW;IACzB,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@zukhruf/fs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.18",
+  "description": "File writes that a reader never sees half done: replace a file in one step, with or without a sync to the disk, or create it only when it is absent. A lock on a file that the kernel frees when its holder dies. Also retries the short refusals of Windows, and names a file after any key.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/fs"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/fs#readme",
+  "keywords": [
+    "fs",
+    "atomic",
+    "write",
+    "durable",
+    "fsync",
+    "rename",
+    "exclusive",
+    "lock",
+    "file-lock",
+    "flock",
+    "sqlite",
+    "windows",
+    "eperm"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}