@deepseek-ai/dsh-atomic-write 0.2.1-alpha.2 → 0.2.1-alpha.3

package/README.i18n.yaml

@@ -9,14 +9,14 @@
   en: ed491d62812ad8cc
   zh: 653e184dd035ec71
 /deepseek-ai-dsh-atomic-write/summary:
-  en: 6c4c49bda04ed05f
-  zh: 1080ddd179d0a3d2
+  en: d2d40e759179f047
+  zh: c53f56de74b26e5a
 /deepseek-ai-dsh-atomic-write/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
 /deepseek-ai-dsh-atomic-write/use-this-package:
-  en: 9cc27a0ee5ae0808
-  zh: d0ee06b54452f600
+  en: 30fbc2c61904195d
+  zh: 09c2ac3f44aa3f08
 /deepseek-ai-dsh-atomic-write/use-this-package/writing-a-file-atomically:
   en: 7b757dc3c3b27335
   zh: a097d90a2561475d
@@ -24,8 +24,8 @@
   en: 77c865c1f78d2a0c
   zh: 5a91874c352c6f18
 /deepseek-ai-dsh-atomic-write/use-this-package/failures-to-plan-for:
-  en: 59308dc757e25273
-  zh: 01113ed577a413cb
+  en: a8292aa69d7f909c
+  zh: 60d8403fa6e04d17
 /deepseek-ai-dsh-atomic-write/understand-the-implementation:
   en: 93b537308f7c88c7
   zh: 282e0d2042aeb1be
@@ -48,8 +48,8 @@
   en: 815e93723a98919c
   zh: 921da870f67e4033
 /deepseek-ai-dsh-atomic-write/known-limitations-and-deferred-work:
-  en: 5d0b395da8833bbb
-  zh: 6191bab46d288be7
+  en: fa413fe1ee23e01f
+  zh: 8563b57f91ea194b
 /deepseek-ai-dsh-atomic-write/known-limitations-and-deferred-work/dev-note:
   en: d3461ceeaf041974
   zh: f59df2adbf52fed9

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-atomic-write` to replace a file without exposing partial content or following a symlinked temporary path. Its writer lock serializes read-modify-write cycles across processes so concurrent writers cannot overwrite one another with stale state. Each replacement uses caller-selected permission bits on a fresh inode, which safely narrows an existing file's permissions. This zero-dependency library accepts strings; it does not provide a `cordis.yml` plugin or crash durability because it does not call `fsync`.
+Use `dsh-atomic-write` to replace a file without exposing partial content or following a symlinked temporary path. Its writer lock serializes read-modify-write cycles across processes so concurrent writers cannot overwrite one another with stale state. Each replacement uses caller-selected permission bits on a fresh inode, which safely narrows an existing file's permissions. This zero-dependency library accepts strings and binary byte arrays; it does not provide a `cordis.yml` plugin or crash durability because it does not call `fsync`.
 
 ## Table of Contents
 
@@ -25,7 +25,7 @@ Use `dsh-atomic-write` to replace a file without exposing partial content or fol
 <a id="use-this-package"></a>
 ## Use this package
 
-Use `writeFileAtomic` when a file-backed store must replace one already-rendered string without ever exposing a partial, symlink-hijacked, or wider-permission state, and `withFileLock` when several processes read-modify-write the same file. The smallest path is one call with the final content and the replacement's permission bits.
+Use `writeFileAtomic` when a file-backed store must replace complete text or binary content without ever exposing a partial, symlink-hijacked, or wider-permission state, and `withFileLock` when several processes read-modify-write the same file. The smallest path is one call with the final content and the replacement's permission bits.
 
 ### Writing a file atomically
 
@@ -60,7 +60,7 @@ Only writers contend — readers never take the lock — and a contender backs o
 
 Windows retries one `EPERM` when the lock cannot be observed, because its holder can release between exclusive creation and the existence check. A repeated unconfirmed `EPERM` is rethrown without running the operation.
 
-The lock's parent directory must already exist, so `withFileLock` rejects an invalid parent hierarchy before running the operation. A process that exits while holding the lock leaves the lock sibling behind, and the next writer takes it over. A lock whose record is empty or incomplete, or names a PID that a live process reused, is not taken over; later writers time out, and an operator removes it only after verifying that no writer still owns it.
+The lock's parent directory must already exist, so `withFileLock` rejects an invalid parent hierarchy before running the operation. A process that exits while holding the lock leaves the lock sibling behind, and the next writer takes it over. A lock whose record is empty or incomplete, or names a PID that a live process reused, is not taken over; later writers time out, and an operator removes it only after verifying that no writer still owns it. An optional `signal` cancels acquisition and contention waits; the operation owns cancellation after it starts.
 
 -----
 
@@ -122,7 +122,7 @@ Nothing here enters a request prefix, so provider cache reuse is unaffected.
 These limits define where the package is not the right tool. They are current package constraints, not a task backlog.
 
 - **Atomic, not durable** — no `fsync` of the file or its directory, so after a crash the rename may be observed unwound. The file-backed stores here re-read and republish on boot, keeping durability the caller's policy.
-- **String content only** — no `Buffer` or stream form until a consumer needs one.
+- **Callers supply complete content** — strings and `Uint8Array` (including `Buffer`) are accepted; streaming writes are unsupported.
 - **Some orphaned locks require operator recovery** — a lock whose record is empty or incomplete, or names a PID a live process reused, stays in place; later writers time out without deleting it. A contender that ends between creating a claim and removing the lock leaves both `<filename>.lock` and `<filename>.lock.takeover-<record hash>`, and the operator removes both.
 - **One host and one PID namespace** — the probe runs on the contender's host. Writers on several hosts sharing a network filesystem, or containers sharing a volume, can see a live holder as exited, take over its lock, and write at the same time as it.
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-使用 `dsh-atomic-write` 替换文件时，不会暴露部分内容，也不会跟随临时路径上的符号链接。它的写锁会跨进程串行化读-修改-写入循环，因此并发写入方不会用陈旧状态相互覆盖。每次替换都会在全新 inode 上使用调用方选择的权限位，从而安全地收窄现有文件的权限。这个零依赖库只接受字符串；它不提供 `cordis.yml` 插件，也不保证崩溃持久性，因为它不调用 `fsync`。
+使用 `dsh-atomic-write` 替换文件时，不会暴露部分内容，也不会跟随临时路径上的符号链接。它的写锁会跨进程串行化读-修改-写入循环，因此并发写入方不会用陈旧状态相互覆盖。每次替换都会在全新 inode 上使用调用方选择的权限位，从而安全地收窄现有文件的权限。这个零依赖库接受字符串和二进制字节数组；它不提供 `cordis.yml` 插件，也不保证崩溃持久性，因为它不调用 `fsync`。
 
 ## 目录
 
@@ -25,7 +25,7 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当文件型存储必须替换一份已渲染好的字符串、且绝不允许暴露部分写入、符号链接劫持或权限过宽状态时，使用 `writeFileAtomic`；当多个进程对同一文件执行读-修改-写入循环时，使用 `withFileLock`。最小路径是一次调用，传入最终内容与替换 inode 的权限位。
+当文件型存储必须替换完整文本或二进制内容、且绝不允许暴露部分写入、符号链接劫持或权限过宽状态时，使用 `writeFileAtomic`；当多个进程对同一文件执行读-修改-写入循环时，使用 `withFileLock`。最小路径是一次调用，传入最终内容与替换 inode 的权限位。
 
 ### 原子写入文件
 
@@ -60,7 +60,7 @@ await withFileLock('/home/u/.dsh/cordis.patch.yml', async () => {
 
 Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可能在独占创建与存在性检查之间释放锁。再次出现无法确认锁存在的 `EPERM` 时，会重新抛出错误且不运行操作。
 
-锁的父目录必须已经存在，因此 `withFileLock` 会在运行操作之前拒绝无效的父目录层级。持锁进程退出时会把锁文件留在原地，下一个写入方会接管它。锁记录为空或不完整，或其 PID 已被存活进程复用时，锁不会被接管；后续写入方超时失败，操作者只有在确认没有写入方仍持有该锁后才会移除它。
+锁的父目录必须已经存在，因此 `withFileLock` 会在运行操作之前拒绝无效的父目录层级。持锁进程退出时会把锁文件留在原地，下一个写入方会接管它。锁记录为空或不完整，或其 PID 已被存活进程复用时，锁不会被接管；后续写入方超时失败，操作者只有在确认没有写入方仍持有该锁后才会移除它。 `signal` 可取消获取锁和等待竞争；操作开始后由操作自身处理取消。
 
 -----
 
@@ -122,7 +122,7 @@ Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可
 这些限制说明本包何时不是合适的工具。它们是当前包约束，不是任务积压。
 
 - **原子但不保证持久**——不对文件或其所在目录做 `fsync`，因此崩溃后可能观察到 rename 被回退。此处的文件型存储在启动时重新读取并重新发布，把持久性留作调用方的策略。
-- **仅支持字符串内容**——在有消费方需要之前，不提供 `Buffer` 或流式形态。
+- **调用方提供完整内容**——接受字符串或 `Uint8Array`（包括 `Buffer`）；不支持流式写入。
 - **部分遗留锁需要操作者恢复**——锁记录为空或不完整，或其 PID 已被存活进程复用时，锁会留在原地；后续写入方超时也不会删除它。竞争者若在创建认领文件与移除锁之间结束，会同时留下 `<filename>.lock` 和 `<filename>.lock.takeover-<记录哈希>`，由操作者删除两者。
 - **单一主机与单一 PID 命名空间**——探测在竞争者所在主机上进行。多台主机通过网络文件系统共享、或多个容器共享同一卷时，写入方可能把存活持有者视为已退出，接管其锁并与之同时写入。
 

package/lib/index.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region lib/types/index.js
 /**
 * Zero-dependency atomic file replacement and writer coordination.
@@ -191,6 +192,7 @@ async function withFileLock(filename, operation, options) {
 	let delay = LOCK_RETRY_INITIAL_MS;
 	let retriedUnconfirmedPermissionError = false;
 	for (;;) {
+		options?.signal?.throwIfAborted();
 		try {
 			await writeFile(lockPath, `${process.pid}\n`, {
 				mode: 384,
@@ -204,10 +206,11 @@ async function withFileLock(filename, operation, options) {
 			} else if (await takeOverExitedLock(lockPath)) continue;
 		}
 		if (Date.now() >= deadline) throw new Error(`atomic-write: timed out waiting for the writer lock at ${lockPath}`);
-		await new Promise((resolve) => setTimeout(resolve, delay));
+		await setTimeout$1(delay, void 0, { signal: options?.signal });
 		delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS);
 	}
 	try {
+		options?.signal?.throwIfAborted();
 		return await operation();
 	} finally {
 		await rm(lockPath, { force: true });

package/lib/types/index.d.ts

@@ -43,9 +43,11 @@ export interface WriteFileAtomicOptions {
  * @param content - complete next file content.
  * @param options - permission bits for the replacement inode.
  */
-export declare function writeFileAtomic(filename: string, content: string, options: WriteFileAtomicOptions): Promise<void>;
+export declare function writeFileAtomic(filename: string, content: string | Uint8Array, options: WriteFileAtomicOptions): Promise<void>;
 /** Options for one {@link withFileLock} acquisition. */
 export interface FileLockOptions {
+    /** Cancel acquisition and contention waits; the operation owns cancellation after it starts. */
+    signal?: AbortSignal;
     /**
      * Maximum time to wait for the lock, in milliseconds. State one when the
      * holder's operation legitimately runs longer than file work — a credential

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-atomic-write",
   "description": "Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)",
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   }
 }