@zgeoff/std 0.3.2 → 0.4.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/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @zgeoff/std
2
2
 
3
3
  Small, dependency-free TypeScript helpers that more than one zgeoff repo needs. Each helper is one
4
- file with its test beside it, exported from the package root, and named by the shared
5
- function-naming rules.
4
+ file with its test beside it, exported from the package root unless it needs Bun, and named by the
5
+ shared function-naming rules.
6
6
 
7
7
  ## Install
8
8
 
@@ -21,16 +21,11 @@ spread, `...(x === undefined ? {} : { x })`, that such code otherwise writes per
21
21
  ```ts
22
22
  import { toExactOptional } from '@zgeoff/std';
23
23
 
24
- interface Options {
25
- label?: string;
26
- retries: number;
27
- }
28
-
29
24
  const label: string | undefined = readLabel();
30
25
 
31
- // { label: string | undefined; retries: number } does not fit Options, but
26
+ // { label: string | undefined; retries: number } does not fit the type, but
32
27
  // toExactOptional's { label?: string; retries: number } does.
33
- const options: Options = toExactOptional({ label, retries: 3 });
28
+ const options: { label?: string; retries: number } = toExactOptional({ label, retries: 3 });
34
29
  ```
35
30
 
36
31
  Own enumerable keys are copied, symbols included, as an object spread would. `null` values stay,
@@ -86,6 +81,12 @@ import { writeStdout } from '@zgeoff/std';
86
81
  process.exitCode = runCheck({ cwd: process.cwd(), writeOutput: writeStdout });
87
82
  ```
88
83
 
84
+ ### `withFileLock`
85
+
86
+ Runs a callback under an exclusive lock on a file that other processes share. It needs Bun, so
87
+ import it from `@zgeoff/std/with-file-lock`; [its doc](../../docs/architecture/std-file-lock.md)
88
+ covers the rest.
89
+
89
90
  ## Typed helpers
90
91
 
91
92
  Each typed helper holds the one type assertion that its job needs, because TypeScript cannot prove
@@ -93,8 +94,5 @@ the type it returns. `toExactOptional` holds one for the same reason. The assert
93
94
  approved disable comment, so code that calls the helper needs no assertion of its own.
94
95
 
95
96
  The typed helpers are `machineTypes`, `pick`, `mergeDeep`, `toTagged` and `toReadonlyDeep`.
96
-
97
- ## Documentation
98
-
99
- [The std typed helpers doc](../../docs/architecture/std-typed-helpers.md) describes each typed
100
- helper, with an example.
97
+ [The std typed helpers doc](../../docs/architecture/std-typed-helpers.md) describes each one, with
98
+ an example.
@@ -0,0 +1,17 @@
1
+ export interface FileLockOwner {
2
+ readonly pid: number;
3
+ readonly host: string;
4
+ readonly token: string;
5
+ readonly acquiredAt: string;
6
+ }
7
+ export type FileLockResult<Value> = {
8
+ readonly kind: 'ran';
9
+ readonly value: Value;
10
+ } | {
11
+ readonly kind: 'busy';
12
+ readonly holder: FileLockOwner | null;
13
+ };
14
+ export interface FileLockOptions {
15
+ readonly waitMs?: number;
16
+ }
17
+ export declare function withFileLock<Value>(path: string, fn: () => Promise<Value>, options?: FileLockOptions): Promise<FileLockResult<Value>>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zgeoff/std",
3
- "version": "0.3.2",
3
+ "version": "0.4.1",
4
4
  "description": "Small, dependency-free TypeScript helpers shared across the zgeoff repos",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -11,6 +11,7 @@
11
11
  "files": [
12
12
  "src",
13
13
  "!src/*.test.ts",
14
+ "!src/test-utils",
14
15
  "dist"
15
16
  ],
16
17
  "type": "module",
@@ -18,6 +19,10 @@
18
19
  ".": {
19
20
  "types": "./dist/index.d.ts",
20
21
  "default": "./src/index.ts"
22
+ },
23
+ "./with-file-lock": {
24
+ "types": "./dist/with-file-lock.d.ts",
25
+ "default": "./src/with-file-lock.ts"
21
26
  }
22
27
  },
23
28
  "publishConfig": {
@@ -29,6 +34,7 @@
29
34
  },
30
35
  "devDependencies": {
31
36
  "@types/bun": "1.4.4",
37
+ "@zgeoff/testing": "0.2.0",
32
38
  "tsrs": "0.18.0-ts7.1.0-dev.20260929",
33
39
  "type-fest": "5.10.0",
34
40
  "typescript": "7.0.2",
@@ -0,0 +1,212 @@
1
+ import type { Pointer } from 'bun:ffi';
2
+ import { FFIType, dlopen, read } from 'bun:ffi';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { closeSync, ftruncateSync, openSync, readFileSync, writeSync } from 'node:fs';
5
+ import { hostname } from 'node:os';
6
+ import { isRecord } from './is-record.ts';
7
+
8
+ export interface FileLockOwner {
9
+ readonly pid: number;
10
+ readonly host: string;
11
+
12
+ // Tells apart two holders that had the same pid, since the kernel reuses a pid.
13
+ readonly token: string;
14
+
15
+ readonly acquiredAt: string;
16
+ }
17
+
18
+ export type FileLockResult<Value> =
19
+ | { readonly kind: 'ran'; readonly value: Value }
20
+ | { readonly kind: 'busy'; readonly holder: FileLockOwner | null };
21
+
22
+ export interface FileLockOptions {
23
+ // How long to wait for another holder to let go before the result is busy. 0 tries once.
24
+ readonly waitMs?: number;
25
+ }
26
+
27
+ // The kernel drops a flock when its holder's descriptor closes, a crash included, so a dead
28
+ // holder's lock needs no takeover. The file stays, since a waiter that opened it before a removal
29
+ // would lock the removed file while a new caller locks its replacement.
30
+ export async function withFileLock<Value>(
31
+ path: string,
32
+ fn: () => Promise<Value>,
33
+ options: FileLockOptions = {},
34
+ ): Promise<FileLockResult<Value>> {
35
+ const descriptor = openSync(path, 'a');
36
+
37
+ try {
38
+ const isLocked = await waitForLock(descriptor, path, options.waitMs ?? 0);
39
+
40
+ if (!isLocked) {
41
+ return { kind: 'busy', holder: readFileLockOwner(path) };
42
+ }
43
+
44
+ writeOwner(descriptor);
45
+
46
+ try {
47
+ return { kind: 'ran', value: await fn() };
48
+ } finally {
49
+ ftruncateSync(descriptor, 0);
50
+ }
51
+ } finally {
52
+ closeSync(descriptor);
53
+ }
54
+ }
55
+
56
+ const retryMs = 25;
57
+
58
+ async function waitForLock(descriptor: number, path: string, waitMs: number): Promise<boolean> {
59
+ const deadlineMs = Date.now() + waitMs;
60
+
61
+ for (;;) {
62
+ if (tryLock(descriptor, path)) {
63
+ return true;
64
+ }
65
+
66
+ if (Date.now() >= deadlineMs) {
67
+ return false;
68
+ }
69
+
70
+ const remainingMs = Math.max(deadlineMs - Date.now(), 0);
71
+
72
+ await Bun.sleep(Math.min(retryMs, remainingMs));
73
+ }
74
+ }
75
+
76
+ const lockExclusive = 2;
77
+ const lockNonBlocking = 4;
78
+
79
+ function tryLock(descriptor: number, path: string): boolean {
80
+ const libc = readLibc();
81
+
82
+ if (libc.flock(descriptor, lockExclusive | lockNonBlocking) === 0) {
83
+ return true;
84
+ }
85
+
86
+ const errno = libc.readErrno();
87
+
88
+ if (errno === libc.wouldBlock) {
89
+ return false;
90
+ }
91
+
92
+ throw new Error(`flock on ${path} failed with errno ${String(errno)}`);
93
+ }
94
+
95
+ interface Libc {
96
+ readonly flock: (descriptor: number, operation: number) => number;
97
+ readonly readErrno: () => number;
98
+ readonly wouldBlock: number;
99
+ }
100
+
101
+ const libcCache: { libc: Libc | null } = { libc: null };
102
+
103
+ // Node and Bun have no flock binding, so the lock calls libc's flock through Bun's FFI.
104
+ function readLibc(): Libc {
105
+ libcCache.libc ??= loadLibc();
106
+
107
+ return libcCache.libc;
108
+ }
109
+
110
+ function loadLibc(): Libc {
111
+ if (process.platform === 'darwin') {
112
+ const library = dlopen('libc.dylib', {
113
+ flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
114
+ __error: { args: [], returns: FFIType.ptr },
115
+ });
116
+
117
+ return {
118
+ flock: library.symbols.flock,
119
+
120
+ // oxlint-disable-next-line no-underscore-dangle -- libc's own symbol name
121
+ readErrno: () => readPointedInt(library.symbols.__error()),
122
+ wouldBlock: 35,
123
+ };
124
+ }
125
+
126
+ const symbols = {
127
+ flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
128
+ __errno_location: { args: [], returns: FFIType.ptr },
129
+ } as const;
130
+
131
+ // A glibc host can also carry musl's loader, so the libc that loads decides, not the files.
132
+ const library = openLinuxLibc(symbols);
133
+
134
+ return {
135
+ flock: library.symbols.flock,
136
+
137
+ // oxlint-disable-next-line no-underscore-dangle -- libc's own symbol name
138
+ readErrno: () => readPointedInt(library.symbols.__errno_location()),
139
+ wouldBlock: 11,
140
+ };
141
+ }
142
+
143
+ function readPointedInt(pointer: Pointer | bigint | null): number {
144
+ if (typeof pointer !== 'number') {
145
+ throw new TypeError('libc returned no errno location');
146
+ }
147
+
148
+ return read.i32(pointer, 0);
149
+ }
150
+
151
+ const muslArchitectures: Partial<Record<NodeJS.Architecture, string>> = {
152
+ arm64: 'aarch64',
153
+ x64: 'x86_64',
154
+ };
155
+
156
+ function openLinuxLibc<Symbols extends Parameters<typeof dlopen>[1]>(symbols: Symbols) {
157
+ try {
158
+ return dlopen('libc.so.6', symbols);
159
+ } catch (error) {
160
+ const muslArchitecture = muslArchitectures[process.arch];
161
+
162
+ if (muslArchitecture === undefined) {
163
+ throw error;
164
+ }
165
+
166
+ return dlopen(`libc.musl-${muslArchitecture}.so.1`, symbols);
167
+ }
168
+ }
169
+
170
+ // A holder can be between its flock and its write, so an empty or partial record reads as null.
171
+ function readFileLockOwner(path: string): FileLockOwner | null {
172
+ try {
173
+ return parseFileLockOwner(readFileSync(path, 'utf8'));
174
+ } catch {
175
+ return null;
176
+ }
177
+ }
178
+
179
+ function parseFileLockOwner(text: string): FileLockOwner | null {
180
+ const value: unknown = JSON.parse(text);
181
+
182
+ if (
183
+ isRecord(value) &&
184
+ typeof value['pid'] === 'number' &&
185
+ typeof value['host'] === 'string' &&
186
+ typeof value['token'] === 'string' &&
187
+ typeof value['acquiredAt'] === 'string'
188
+ ) {
189
+ return {
190
+ pid: value['pid'],
191
+ host: value['host'],
192
+ token: value['token'],
193
+ acquiredAt: value['acquiredAt'],
194
+ };
195
+ }
196
+
197
+ return null;
198
+ }
199
+
200
+ // The record goes in only after the flock is held, so a caller that finds the lock busy never
201
+ // truncates the holder's record.
202
+ function writeOwner(descriptor: number): void {
203
+ const owner: FileLockOwner = {
204
+ pid: process.pid,
205
+ host: hostname(),
206
+ token: randomUUID(),
207
+ acquiredAt: new Date().toISOString(),
208
+ };
209
+
210
+ ftruncateSync(descriptor, 0);
211
+ writeSync(descriptor, JSON.stringify(owner));
212
+ }