@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 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.2.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
- "prepare": "bun run build",
29
- "typecheck": "tsc"
28
+ "typecheck": "tsrs"
30
29
  },
31
30
  "devDependencies": {
32
- "@types/bun": "1.4.2",
33
- "typescript": "7.0.2"
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';
@@ -0,0 +1,6 @@
1
+ export function isOneOf<const T extends readonly unknown[]>(
2
+ value: unknown,
3
+ options: T,
4
+ ): value is T[number] {
5
+ return options.includes(value);
6
+ }
@@ -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
+ }
@@ -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
- // Flattens an intersection into one object type, so editors show its keys.
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/no-unsafe-type-assertion -- the filter above is what makes the keys optional; the type system cannot follow it
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
+ }
@@ -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
+ }