@zgeoff/std 0.3.0 → 0.3.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 +19 -57
- package/dist/index.d.ts +2 -0
- package/dist/read-optional-text.d.ts +1 -0
- package/dist/write-stdout.d.ts +1 -0
- package/package.json +5 -5
- package/src/index.ts +2 -0
- package/src/merge-deep.ts +0 -1
- package/src/read-optional-text.ts +23 -0
- package/src/to-exact-optional.ts +1 -7
- package/src/write-stdout.ts +4 -0
package/README.md
CHANGED
|
@@ -63,76 +63,38 @@ const sizes = ['small', 'large'] as const;
|
|
|
63
63
|
const size = isOneOf(input, sizes) ? input : 'small';
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
Each helper in this section holds the one type assertion that its job needs, because TypeScript
|
|
69
|
-
cannot prove the type it returns. `toExactOptional` holds one for the same reason. The assertion
|
|
70
|
-
carries an approved disable comment, so code that calls the helper needs no assertion of its own.
|
|
71
|
-
|
|
72
|
-
### `machineTypes`
|
|
73
|
-
|
|
74
|
-
Returns the `types` value of an xstate `setup()` or `createMachine()` call. xstate reads `types`
|
|
75
|
-
only at compile time, and its documentation fills it with `{} as X`. The type argument names only
|
|
76
|
-
the keys xstate reads from `types`, such as `context`, `events`, `input` and `actors`, so a key
|
|
77
|
-
outside that set fails the type check. A key left out keeps xstate's default.
|
|
78
|
-
|
|
79
|
-
```ts
|
|
80
|
-
import { machineTypes } from '@zgeoff/std';
|
|
81
|
-
import { setup } from 'xstate';
|
|
82
|
-
|
|
83
|
-
const doorMachine = setup({
|
|
84
|
-
types: machineTypes<{ context: { opens: number }; events: { type: 'open' } }>(),
|
|
85
|
-
}).createMachine({ context: { opens: 0 } });
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### `pick`
|
|
66
|
+
### `readOptionalText`
|
|
89
67
|
|
|
90
|
-
|
|
91
|
-
|
|
68
|
+
Reads a file's text, or returns `undefined` when the file or a folder on its path does not exist. It
|
|
69
|
+
reads to the end of the file, so a procfs or cgroupfs file that reports a size of 0 still reads in
|
|
70
|
+
full. Any other failure, such as a path that names a folder, throws.
|
|
92
71
|
|
|
93
72
|
```ts
|
|
94
|
-
import {
|
|
73
|
+
import { readOptionalText } from '@zgeoff/std';
|
|
95
74
|
|
|
96
|
-
const
|
|
75
|
+
const lefthook = await readOptionalText('lefthook.yml');
|
|
97
76
|
```
|
|
98
77
|
|
|
99
|
-
### `
|
|
78
|
+
### `writeStdout`
|
|
100
79
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
the result keeps the base object's prototype, so a class instance stays one. An array, a function, a
|
|
104
|
-
`Date`, a `RegExp`, a `Map`, a `Set` or a `Promise` replaces the base value whole. The base and the
|
|
105
|
-
patch stay untouched. The `PartialDeep<T>` type describes the patch.
|
|
80
|
+
Writes a text to stdout as it is, with no newline added. Pass it as the `writeOutput` of a command's
|
|
81
|
+
options at its entry point, so a test hands in its own writer.
|
|
106
82
|
|
|
107
83
|
```ts
|
|
108
|
-
import {
|
|
84
|
+
import { writeStdout } from '@zgeoff/std';
|
|
109
85
|
|
|
110
|
-
|
|
86
|
+
process.exitCode = runCheck({ cwd: process.cwd(), writeOutput: writeStdout });
|
|
111
87
|
```
|
|
112
88
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
Returns a string, number or bigint typed as a tagged type, such as type-fest's
|
|
116
|
-
`Tagged<string, 'OrderID'>`. It takes the untagged base type and refuses a type that carries no tag,
|
|
117
|
-
such as a literal union, so it never narrows a value to a set of literals.
|
|
118
|
-
|
|
119
|
-
```ts
|
|
120
|
-
import { toTagged } from '@zgeoff/std';
|
|
121
|
-
import type { Tagged } from 'type-fest';
|
|
122
|
-
|
|
123
|
-
type OrderID = Tagged<string, 'OrderID'>;
|
|
124
|
-
|
|
125
|
-
const orderID = toTagged<OrderID>(crypto.randomUUID());
|
|
126
|
-
```
|
|
89
|
+
## Typed helpers
|
|
127
90
|
|
|
128
|
-
|
|
91
|
+
Each typed helper holds the one type assertion that its job needs, because TypeScript cannot prove
|
|
92
|
+
the type it returns. `toExactOptional` holds one for the same reason. The assertion carries an
|
|
93
|
+
approved disable comment, so code that calls the helper needs no assertion of its own.
|
|
129
94
|
|
|
130
|
-
|
|
131
|
-
readonly array, a `Map` as a `ReadonlyMap` and a `Set` as a `ReadonlySet`. It freezes nothing at run
|
|
132
|
-
time. A function, a `Date`, a `RegExp` and a `Promise` keep their own type.
|
|
95
|
+
The typed helpers are `machineTypes`, `pick`, `mergeDeep`, `toTagged` and `toReadonlyDeep`.
|
|
133
96
|
|
|
134
|
-
|
|
135
|
-
import { toReadonlyDeep } from '@zgeoff/std';
|
|
97
|
+
## Documentation
|
|
136
98
|
|
|
137
|
-
|
|
138
|
-
|
|
99
|
+
[The std typed helpers doc](../../docs/architecture/std-typed-helpers.md) describes each typed
|
|
100
|
+
helper, with an example.
|
package/dist/index.d.ts
CHANGED
|
@@ -3,6 +3,8 @@ export { isRecord } from './is-record.ts';
|
|
|
3
3
|
export { type MachineTypeKey, machineTypes } from './machine-types.ts';
|
|
4
4
|
export { mergeDeep, type PartialDeep } from './merge-deep.ts';
|
|
5
5
|
export { pick } from './pick.ts';
|
|
6
|
+
export { readOptionalText } from './read-optional-text.ts';
|
|
6
7
|
export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
|
|
7
8
|
export { type ReadonlyDeep, toReadonlyDeep } from './to-readonly-deep.ts';
|
|
8
9
|
export { toTagged } from './to-tagged.ts';
|
|
10
|
+
export { writeStdout } from './write-stdout.ts';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function readOptionalText(path: string): Promise<string | undefined>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function writeStdout(text: string): void;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zgeoff/std",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"description": "Small, dependency-free TypeScript helpers shared across the zgeoff repos",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -25,14 +25,14 @@
|
|
|
25
25
|
},
|
|
26
26
|
"scripts": {
|
|
27
27
|
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
28
|
-
"
|
|
29
|
-
"typecheck": "tsc"
|
|
28
|
+
"typecheck": "tsrs"
|
|
30
29
|
},
|
|
31
30
|
"devDependencies": {
|
|
32
|
-
"@types/bun": "1.4.
|
|
31
|
+
"@types/bun": "1.4.4",
|
|
32
|
+
"tsrs": "0.18.0-ts7.1.0-dev.20260929",
|
|
33
33
|
"type-fest": "5.10.0",
|
|
34
34
|
"typescript": "7.0.2",
|
|
35
|
-
"xstate": "5.33.
|
|
35
|
+
"xstate": "5.33.3"
|
|
36
36
|
},
|
|
37
37
|
"engines": {
|
|
38
38
|
"bun": ">=1.3"
|
package/src/index.ts
CHANGED
|
@@ -3,6 +3,8 @@ export { isRecord } from './is-record.ts';
|
|
|
3
3
|
export { type MachineTypeKey, machineTypes } from './machine-types.ts';
|
|
4
4
|
export { mergeDeep, type PartialDeep } from './merge-deep.ts';
|
|
5
5
|
export { pick } from './pick.ts';
|
|
6
|
+
export { readOptionalText } from './read-optional-text.ts';
|
|
6
7
|
export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
|
|
7
8
|
export { type ReadonlyDeep, toReadonlyDeep } from './to-readonly-deep.ts';
|
|
8
9
|
export { toTagged } from './to-tagged.ts';
|
|
10
|
+
export { writeStdout } from './write-stdout.ts';
|
package/src/merge-deep.ts
CHANGED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
|
|
3
|
+
// Bun.file's text reads as many bytes as stat reports, and procfs and cgroupfs report 0 for every
|
|
4
|
+
// file; readFile reads to the end.
|
|
5
|
+
export async function readOptionalText(path: string): Promise<string | undefined> {
|
|
6
|
+
try {
|
|
7
|
+
return await readFile(path, 'utf8');
|
|
8
|
+
} catch (error) {
|
|
9
|
+
if (isMissingFileError(error)) {
|
|
10
|
+
return undefined;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
throw error;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function isMissingFileError(error: unknown): boolean {
|
|
18
|
+
return (
|
|
19
|
+
error instanceof Error &&
|
|
20
|
+
'code' in error &&
|
|
21
|
+
(error.code === 'ENOENT' || error.code === 'ENOTDIR')
|
|
22
|
+
);
|
|
23
|
+
}
|
package/src/to-exact-optional.ts
CHANGED
|
@@ -1,14 +1,10 @@
|
|
|
1
|
-
// The keys whose value type admits undefined, an optional key among them.
|
|
2
1
|
type UndefinedKeys<T> = {
|
|
3
2
|
[K in keyof T]-?: undefined extends T[K] ? K : never;
|
|
4
3
|
}[keyof T];
|
|
5
4
|
|
|
6
|
-
//
|
|
5
|
+
// Editors list an intersection's keys only once it is flattened into one object type.
|
|
7
6
|
type Simplify<T> = { [K in keyof T]: T[K] };
|
|
8
7
|
|
|
9
|
-
// T with each key that admits undefined made optional and its undefined dropped:
|
|
10
|
-
// { a: string | undefined; b: number } becomes { a?: string; b: number }. A union
|
|
11
|
-
// maps member by member, so each member keeps its own keys.
|
|
12
8
|
export type ExactOptional<T extends object> = T extends unknown
|
|
13
9
|
? Simplify<
|
|
14
10
|
Pick<T, Exclude<keyof T, UndefinedKeys<T>>> & {
|
|
@@ -17,8 +13,6 @@ export type ExactOptional<T extends object> = T extends unknown
|
|
|
17
13
|
>
|
|
18
14
|
: never;
|
|
19
15
|
|
|
20
|
-
// Returns a new object with the own enumerable keys of `value`, symbols included,
|
|
21
|
-
// whose value is not undefined; null values stay, and `value` is left untouched.
|
|
22
16
|
export function toExactOptional<T extends object>(value: T): ExactOptional<T> {
|
|
23
17
|
const entries = Reflect.ownKeys(value)
|
|
24
18
|
.filter((key) => Object.prototype.propertyIsEnumerable.call(value, key))
|