@zgeoff/std 0.4.0 → 0.4.2
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 +12 -14
- package/dist/with-file-lock.d.ts +17 -0
- package/package.json +7 -1
- package/src/with-file-lock.ts +212 -0
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
|
|
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
|
|
26
|
+
// { label: string | undefined; retries: number } does not fit the type, but
|
|
32
27
|
// toExactOptional's { label?: string; retries: number } does.
|
|
33
|
-
const options:
|
|
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
|
-
|
|
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.4.
|
|
3
|
+
"version": "0.4.2",
|
|
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.1",
|
|
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
|
+
}
|