@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 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
- ## 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`
66
+ ### `readOptionalText`
89
67
 
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`.
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 { pick } from '@zgeoff/std';
73
+ import { readOptionalText } from '@zgeoff/std';
95
74
 
96
- const summary = pick(order, ['id', 'total']);
75
+ const lefthook = await readOptionalText('lefthook.yml');
97
76
  ```
98
77
 
99
- ### `mergeDeep`
78
+ ### `writeStdout`
100
79
 
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.
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 { mergeDeep } from '@zgeoff/std';
84
+ import { writeStdout } from '@zgeoff/std';
109
85
 
110
- const settings = mergeDeep(defaultSettings, { theme: { size: 14 } });
86
+ process.exitCode = runCheck({ cwd: process.cwd(), writeOutput: writeStdout });
111
87
  ```
112
88
 
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
- ```
89
+ ## Typed helpers
127
90
 
128
- ### `toReadonlyDeep`
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
- 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.
95
+ The typed helpers are `machineTypes`, `pick`, `mergeDeep`, `toTagged` and `toReadonlyDeep`.
133
96
 
134
- ```ts
135
- import { toReadonlyDeep } from '@zgeoff/std';
97
+ ## Documentation
136
98
 
137
- const config = toReadonlyDeep(parseConfig(text));
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.0",
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
- "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.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.2"
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
@@ -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))
@@ -0,0 +1,4 @@
1
+ // The writeOutput a command's entry point hands its options: each text goes to stdout as it is.
2
+ export function writeStdout(text: string): void {
3
+ process.stdout.write(text);
4
+ }