@zgeoff/std 0.3.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
@@ -63,76 +63,27 @@ const sizes = ['small', 'large'] as const;
63
63
  const size = isOneOf(input, sizes) ? input : 'small';
64
64
  ```
65
65
 
66
- ## Typed helpers
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`
89
-
90
- Returns a copy of an object with only the listed keys, typed as `Pick<T, K>`. A listed key that the
91
- object lacks stays out of the copy, so an optional key never holds an explicit `undefined`.
92
-
93
- ```ts
94
- import { pick } from '@zgeoff/std';
66
+ ### `readOptionalText`
95
67
 
96
- const summary = pick(order, ['id', 'total']);
97
- ```
98
-
99
- ### `mergeDeep`
100
-
101
- Merges a deep partial of an object over the whole object and returns a new object of the same type.
102
- A plain object in the patch merges key by key over an object in the base, at the root or nested, and
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.
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.
106
71
 
107
72
  ```ts
108
- import { mergeDeep } from '@zgeoff/std';
73
+ import { readOptionalText } from '@zgeoff/std';
109
74
 
110
- const settings = mergeDeep(defaultSettings, { theme: { size: 14 } });
75
+ const lefthook = await readOptionalText('lefthook.yml');
111
76
  ```
112
77
 
113
- ### `toTagged`
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
- ```
78
+ ## Typed helpers
127
79
 
128
- ### `toReadonlyDeep`
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.
129
83
 
130
- Returns a value unchanged, typed as `ReadonlyDeep<T>`: every nested key readonly, an array as a
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.
84
+ The typed helpers are `machineTypes`, `pick`, `mergeDeep`, `toTagged` and `toReadonlyDeep`.
133
85
 
134
- ```ts
135
- import { toReadonlyDeep } from '@zgeoff/std';
86
+ ## Documentation
136
87
 
137
- const config = toReadonlyDeep(parseConfig(text));
138
- ```
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
@@ -3,6 +3,7 @@ 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';
@@ -0,0 +1 @@
1
+ export declare function readOptionalText(path: string): Promise<string | undefined>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zgeoff/std",
3
- "version": "0.3.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,14 +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",
31
+ "@types/bun": "1.4.3",
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.2"
35
+ "xstate": "5.33.3"
36
36
  },
37
37
  "engines": {
38
38
  "bun": ">=1.3"
package/src/index.ts CHANGED
@@ -3,6 +3,7 @@ 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';
package/src/merge-deep.ts CHANGED
@@ -1,6 +1,5 @@
1
1
  import { types } from 'node:util';
2
2
 
3
- // A value the merge replaces whole rather than merging key by key.
4
3
  type WholeValue =
5
4
  | readonly unknown[]
6
5
  | ((...args: never[]) => unknown)
@@ -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,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))