@zgeoff/std 0.2.0 → 0.3.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 +39 -0
- package/dist/index.d.ts +7 -0
- package/dist/is-one-of.d.ts +1 -0
- package/dist/machine-types.d.ts +4 -0
- package/dist/merge-deep.d.ts +6 -0
- package/dist/pick.d.ts +1 -0
- package/dist/read-optional-text.d.ts +1 -0
- package/dist/to-readonly-deep.d.ts +6 -0
- package/dist/to-tagged.d.ts +6 -0
- package/package.json +7 -5
- package/src/index.ts +7 -0
- package/src/is-one-of.ts +6 -0
- package/src/machine-types.ts +24 -0
- package/src/merge-deep.ts +73 -0
- package/src/pick.ts +9 -0
- package/src/read-optional-text.ts +23 -0
- package/src/to-exact-optional.ts +2 -8
- package/src/to-readonly-deep.ts +17 -0
- package/src/to-tagged.ts +24 -0
package/README.md
CHANGED
|
@@ -48,3 +48,42 @@ import { isRecord } from '@zgeoff/std';
|
|
|
48
48
|
const parsed: unknown = JSON.parse(text);
|
|
49
49
|
const name = isRecord(parsed) ? parsed['name'] : undefined;
|
|
50
50
|
```
|
|
51
|
+
|
|
52
|
+
### `isOneOf`
|
|
53
|
+
|
|
54
|
+
Tells whether a value is one of a list of values, and narrows it to the list's element type, so a
|
|
55
|
+
string read from outside the program becomes a literal union without a cast. It compares with
|
|
56
|
+
`Array.prototype.includes`, so `NaN` matches `NaN`.
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { isOneOf } from '@zgeoff/std';
|
|
60
|
+
|
|
61
|
+
const sizes = ['small', 'large'] as const;
|
|
62
|
+
|
|
63
|
+
const size = isOneOf(input, sizes) ? input : 'small';
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### `readOptionalText`
|
|
67
|
+
|
|
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.
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import { readOptionalText } from '@zgeoff/std';
|
|
74
|
+
|
|
75
|
+
const lefthook = await readOptionalText('lefthook.yml');
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Typed helpers
|
|
79
|
+
|
|
80
|
+
Each typed helper holds the one type assertion that its job needs, because TypeScript cannot prove
|
|
81
|
+
the type it returns. `toExactOptional` holds one for the same reason. The assertion carries an
|
|
82
|
+
approved disable comment, so code that calls the helper needs no assertion of its own.
|
|
83
|
+
|
|
84
|
+
The typed helpers are `machineTypes`, `pick`, `mergeDeep`, `toTagged` and `toReadonlyDeep`.
|
|
85
|
+
|
|
86
|
+
## Documentation
|
|
87
|
+
|
|
88
|
+
[The std typed helpers doc](../../docs/architecture/std-typed-helpers.md) describes each typed
|
|
89
|
+
helper, with an example.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,9 @@
|
|
|
1
|
+
export { isOneOf } from './is-one-of.ts';
|
|
1
2
|
export { isRecord } from './is-record.ts';
|
|
3
|
+
export { type MachineTypeKey, machineTypes } from './machine-types.ts';
|
|
4
|
+
export { mergeDeep, type PartialDeep } from './merge-deep.ts';
|
|
5
|
+
export { pick } from './pick.ts';
|
|
6
|
+
export { readOptionalText } from './read-optional-text.ts';
|
|
2
7
|
export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
|
|
8
|
+
export { type ReadonlyDeep, toReadonlyDeep } from './to-readonly-deep.ts';
|
|
9
|
+
export { toTagged } from './to-tagged.ts';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function isOneOf<const T extends readonly unknown[]>(value: unknown, options: T): value is T[number];
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export type MachineTypeKey = 'context' | 'events' | 'children' | 'tags' | 'input' | 'output' | 'emitted' | 'meta' | 'transitionMeta' | 'actors' | 'actions' | 'guards' | 'delays';
|
|
2
|
+
type MachineTypeSpec = Partial<Readonly<Record<MachineTypeKey, unknown>>>;
|
|
3
|
+
export declare function machineTypes<T extends MachineTypeSpec & Record<Exclude<keyof T, MachineTypeKey>, never>>(): T;
|
|
4
|
+
export {};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
type WholeValue = readonly unknown[] | ((...args: never[]) => unknown) | Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | Promise<unknown>;
|
|
2
|
+
export type PartialDeep<T> = T extends WholeValue ? T : T extends object ? {
|
|
3
|
+
[K in keyof T]?: PartialDeep<T[K]>;
|
|
4
|
+
} : T;
|
|
5
|
+
export declare function mergeDeep<T extends object>(base: T, patch: PartialDeep<T>): T;
|
|
6
|
+
export {};
|
package/dist/pick.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function pick<T extends object, K extends keyof T>(value: T, keys: readonly K[]): Pick<T, K>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function readOptionalText(path: string): Promise<string | undefined>;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
type OpaqueValue = ((...args: never[]) => unknown) | Date | RegExp | Promise<unknown>;
|
|
2
|
+
export type ReadonlyDeep<T> = T extends OpaqueValue ? T : T extends ReadonlyMap<infer Key, infer Item> ? ReadonlyMap<ReadonlyDeep<Key>, ReadonlyDeep<Item>> : T extends ReadonlySet<infer Item> ? ReadonlySet<ReadonlyDeep<Item>> : T extends object ? {
|
|
3
|
+
readonly [K in keyof T]: ReadonlyDeep<T[K]>;
|
|
4
|
+
} : T;
|
|
5
|
+
export declare function toReadonlyDeep<T>(value: T): ReadonlyDeep<T>;
|
|
6
|
+
export {};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
type TaggedBase = string | number | bigint;
|
|
2
|
+
type Untagged<T> = T extends string ? string : T extends number ? number : T extends bigint ? bigint : never;
|
|
3
|
+
type TagKey<T> = Exclude<keyof T, keyof Untagged<T>>;
|
|
4
|
+
type TaggedSource<T> = [TagKey<T>] extends [never] ? never : Untagged<T> & Pick<T, TagKey<T>> extends T ? Untagged<T> : never;
|
|
5
|
+
export declare function toTagged<T extends TaggedBase>(value: TaggedSource<T>): T;
|
|
6
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zgeoff/std",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "Small, dependency-free TypeScript helpers shared across the zgeoff repos",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -25,12 +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.
|
|
33
|
-
"
|
|
31
|
+
"@types/bun": "1.4.3",
|
|
32
|
+
"tsrs": "0.18.0-ts7.1.0-dev.20260929",
|
|
33
|
+
"type-fest": "5.10.0",
|
|
34
|
+
"typescript": "7.0.2",
|
|
35
|
+
"xstate": "5.33.3"
|
|
34
36
|
},
|
|
35
37
|
"engines": {
|
|
36
38
|
"bun": ">=1.3"
|
package/src/index.ts
CHANGED
|
@@ -1,2 +1,9 @@
|
|
|
1
|
+
export { isOneOf } from './is-one-of.ts';
|
|
1
2
|
export { isRecord } from './is-record.ts';
|
|
3
|
+
export { type MachineTypeKey, machineTypes } from './machine-types.ts';
|
|
4
|
+
export { mergeDeep, type PartialDeep } from './merge-deep.ts';
|
|
5
|
+
export { pick } from './pick.ts';
|
|
6
|
+
export { readOptionalText } from './read-optional-text.ts';
|
|
2
7
|
export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
|
|
8
|
+
export { type ReadonlyDeep, toReadonlyDeep } from './to-readonly-deep.ts';
|
|
9
|
+
export { toTagged } from './to-tagged.ts';
|
package/src/is-one-of.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// The keys xstate reads from `types` in setup() and in createMachine().
|
|
2
|
+
export type MachineTypeKey =
|
|
3
|
+
| 'context'
|
|
4
|
+
| 'events'
|
|
5
|
+
| 'children'
|
|
6
|
+
| 'tags'
|
|
7
|
+
| 'input'
|
|
8
|
+
| 'output'
|
|
9
|
+
| 'emitted'
|
|
10
|
+
| 'meta'
|
|
11
|
+
| 'transitionMeta'
|
|
12
|
+
| 'actors'
|
|
13
|
+
| 'actions'
|
|
14
|
+
| 'guards'
|
|
15
|
+
| 'delays';
|
|
16
|
+
|
|
17
|
+
type MachineTypeSpec = Partial<Readonly<Record<MachineTypeKey, unknown>>>;
|
|
18
|
+
|
|
19
|
+
export function machineTypes<
|
|
20
|
+
T extends MachineTypeSpec & Record<Exclude<keyof T, MachineTypeKey>, never>,
|
|
21
|
+
>(): T {
|
|
22
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: xstate v5 documents only `{} as X` for setup({ types }), and reads the value only at compile time
|
|
23
|
+
return {} as T;
|
|
24
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { types } from 'node:util';
|
|
2
|
+
|
|
3
|
+
type WholeValue =
|
|
4
|
+
| readonly unknown[]
|
|
5
|
+
| ((...args: never[]) => unknown)
|
|
6
|
+
| Date
|
|
7
|
+
| RegExp
|
|
8
|
+
| ReadonlyMap<unknown, unknown>
|
|
9
|
+
| ReadonlySet<unknown>
|
|
10
|
+
| Promise<unknown>;
|
|
11
|
+
|
|
12
|
+
export type PartialDeep<T> = T extends WholeValue
|
|
13
|
+
? T
|
|
14
|
+
: T extends object
|
|
15
|
+
? { [K in keyof T]?: PartialDeep<T[K]> }
|
|
16
|
+
: T;
|
|
17
|
+
|
|
18
|
+
export function mergeDeep<T extends object>(base: T, patch: PartialDeep<T>): T {
|
|
19
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: TypeScript cannot prove that a deep partial merged over T gives T
|
|
20
|
+
return mergeValues(base, patch) as T;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function mergeValues(base: unknown, patch: unknown): unknown {
|
|
24
|
+
return isMergeable(base) && isPlainObject(patch) ? mergeRecords(base, patch) : patch;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function isMergeable(value: unknown): value is object {
|
|
28
|
+
return (
|
|
29
|
+
typeof value === 'object' &&
|
|
30
|
+
value !== null &&
|
|
31
|
+
!Array.isArray(value) &&
|
|
32
|
+
!types.isDate(value) &&
|
|
33
|
+
!types.isRegExp(value) &&
|
|
34
|
+
!types.isMap(value) &&
|
|
35
|
+
!types.isSet(value) &&
|
|
36
|
+
!types.isPromise(value)
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function isPlainObject(value: unknown): value is object {
|
|
41
|
+
if (typeof value !== 'object' || value === null) {
|
|
42
|
+
return false;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const prototype: unknown = Object.getPrototypeOf(value);
|
|
46
|
+
|
|
47
|
+
return prototype === Object.prototype || prototype === null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function mergeRecords(base: object, patch: object): object {
|
|
51
|
+
const merged: object = { ...base };
|
|
52
|
+
|
|
53
|
+
Reflect.setPrototypeOf(merged, Reflect.getPrototypeOf(base));
|
|
54
|
+
|
|
55
|
+
for (const key of Reflect.ownKeys(patch)) {
|
|
56
|
+
if (Object.prototype.propertyIsEnumerable.call(patch, key)) {
|
|
57
|
+
const current: unknown = Object.getOwnPropertyDescriptor(merged, key)?.value;
|
|
58
|
+
const next: unknown = Reflect.get(patch, key);
|
|
59
|
+
const value = mergeValues(current, next);
|
|
60
|
+
|
|
61
|
+
// an assignment to a `__proto__` key calls the inherited setter and
|
|
62
|
+
// replaces the prototype, so each key is defined as an own data property
|
|
63
|
+
Object.defineProperty(merged, key, {
|
|
64
|
+
value,
|
|
65
|
+
writable: true,
|
|
66
|
+
enumerable: true,
|
|
67
|
+
configurable: true,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
return merged;
|
|
73
|
+
}
|
package/src/pick.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export function pick<T extends object, K extends keyof T>(
|
|
2
|
+
value: T,
|
|
3
|
+
keys: readonly K[],
|
|
4
|
+
): Pick<T, K> {
|
|
5
|
+
const entries = keys.filter((key) => key in value).map((key): [K, T[K]] => [key, value[key]]);
|
|
6
|
+
|
|
7
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: Object.fromEntries loses key types inside a generic
|
|
8
|
+
return Object.fromEntries(entries) as Pick<T, K>;
|
|
9
|
+
}
|
|
@@ -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,14 +13,12 @@ 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))
|
|
25
19
|
.map((key): [PropertyKey, unknown] => [key, Reflect.get(value, key)])
|
|
26
20
|
.filter(([, entry]) => entry !== undefined);
|
|
27
21
|
|
|
28
|
-
// oxlint-disable-next-line typescript/
|
|
22
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: Object.fromEntries loses key types inside a generic
|
|
29
23
|
return Object.fromEntries(entries) as ExactOptional<T>;
|
|
30
24
|
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// A value whose own methods a readonly mapped type would break.
|
|
2
|
+
type OpaqueValue = ((...args: never[]) => unknown) | Date | RegExp | Promise<unknown>;
|
|
3
|
+
|
|
4
|
+
export type ReadonlyDeep<T> = T extends OpaqueValue
|
|
5
|
+
? T
|
|
6
|
+
: T extends ReadonlyMap<infer Key, infer Item>
|
|
7
|
+
? ReadonlyMap<ReadonlyDeep<Key>, ReadonlyDeep<Item>>
|
|
8
|
+
: T extends ReadonlySet<infer Item>
|
|
9
|
+
? ReadonlySet<ReadonlyDeep<Item>>
|
|
10
|
+
: T extends object
|
|
11
|
+
? { readonly [K in keyof T]: ReadonlyDeep<T[K]> }
|
|
12
|
+
: T;
|
|
13
|
+
|
|
14
|
+
export function toReadonlyDeep<T>(value: T): ReadonlyDeep<T> {
|
|
15
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: TypeScript cannot resolve the conditional type inside the generic
|
|
16
|
+
return value as ReadonlyDeep<T>;
|
|
17
|
+
}
|
package/src/to-tagged.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
type TaggedBase = string | number | bigint;
|
|
2
|
+
|
|
3
|
+
type Untagged<T> = T extends string
|
|
4
|
+
? string
|
|
5
|
+
: T extends number
|
|
6
|
+
? number
|
|
7
|
+
: T extends bigint
|
|
8
|
+
? bigint
|
|
9
|
+
: never;
|
|
10
|
+
|
|
11
|
+
type TagKey<T> = Exclude<keyof T, keyof Untagged<T>>;
|
|
12
|
+
|
|
13
|
+
type TaggedSource<T> = [TagKey<T>] extends [never]
|
|
14
|
+
? never
|
|
15
|
+
: Untagged<T> & Pick<T, TagKey<T>> extends T
|
|
16
|
+
? Untagged<T>
|
|
17
|
+
: never;
|
|
18
|
+
|
|
19
|
+
export function toTagged<T extends TaggedBase>(value: TaggedSource<T>): T {
|
|
20
|
+
const untagged: unknown = value;
|
|
21
|
+
|
|
22
|
+
// oxlint-disable-next-line typescript/consistent-type-assertions -- approved GEO-1460: a type-fest Tagged value cannot be made without a cast
|
|
23
|
+
return untagged as T;
|
|
24
|
+
}
|