@zgeoff/std 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Geoff Whatley
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,50 @@
1
- # Temporary Holding Version
1
+ # @zgeoff/std
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Small, dependency-free TypeScript helpers that more than one zgeoff repo needs. Each helper is one
4
+ file with its test beside it, exported from the package root, and named by the shared function-verb
5
+ rules.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ bun add @zgeoff/std
11
+ ```
12
+
13
+ ## Helpers
14
+
15
+ ### `toExactOptional`
16
+
17
+ Returns a copy of an object without the keys whose value is `undefined`, typed so the copy fits a
18
+ type with optional properties under `exactOptionalPropertyTypes`. It replaces the conditional
19
+ spread, `...(x === undefined ? {} : { x })`, that such code otherwise writes per key.
20
+
21
+ ```ts
22
+ import { toExactOptional } from '@zgeoff/std';
23
+
24
+ interface Options {
25
+ label?: string;
26
+ retries: number;
27
+ }
28
+
29
+ const label: string | undefined = readLabel();
30
+
31
+ // { label: string | undefined; retries: number } does not fit Options, but
32
+ // toExactOptional's { label?: string; retries: number } does.
33
+ const options: Options = toExactOptional({ label, retries: 3 });
34
+ ```
35
+
36
+ Own enumerable keys are copied, symbols included, as an object spread would. `null` values stay,
37
+ falsy values such as `0` and `''` stay, and the input object is left untouched. A union input maps
38
+ member by member, so each member keeps its own keys.
39
+
40
+ ### `isRecord`
41
+
42
+ Tells whether a value is a plain keyed object, and narrows it to `Record<string, unknown>`, so code
43
+ that reads parsed JSON can index it. An array or `null` is not a record.
44
+
45
+ ```ts
46
+ import { isRecord } from '@zgeoff/std';
47
+
48
+ const parsed: unknown = JSON.parse(text);
49
+ const name = isRecord(parsed) ? parsed['name'] : undefined;
50
+ ```
@@ -0,0 +1,2 @@
1
+ export { isRecord } from './is-record.ts';
2
+ export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
@@ -0,0 +1 @@
1
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
@@ -0,0 +1,11 @@
1
+ type UndefinedKeys<T> = {
2
+ [K in keyof T]-?: undefined extends T[K] ? K : never;
3
+ }[keyof T];
4
+ type Simplify<T> = {
5
+ [K in keyof T]: T[K];
6
+ };
7
+ export type ExactOptional<T extends object> = T extends unknown ? Simplify<Pick<T, Exclude<keyof T, UndefinedKeys<T>>> & {
8
+ [K in keyof Pick<T, UndefinedKeys<T>>]?: Exclude<T[K], undefined>;
9
+ }> : never;
10
+ export declare function toExactOptional<T extends object>(value: T): ExactOptional<T>;
11
+ export {};
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "@zgeoff/std",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Small, dependency-free TypeScript helpers shared across the zgeoff repos",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/zgeoff/tools.git",
9
+ "directory": "packages/std"
10
+ },
11
+ "files": [
12
+ "src",
13
+ "!src/*.test.ts",
14
+ "dist"
15
+ ],
16
+ "type": "module",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "default": "./src/index.ts"
21
+ }
22
+ },
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "scripts": {
27
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
28
+ "prepare": "bun run build",
29
+ "typecheck": "tsc"
30
+ },
31
+ "devDependencies": {
32
+ "@types/bun": "1.4.2",
33
+ "typescript": "7.0.2"
34
+ },
35
+ "engines": {
36
+ "bun": ">=1.3"
37
+ }
38
+ }
package/src/index.ts ADDED
@@ -0,0 +1,2 @@
1
+ export { isRecord } from './is-record.ts';
2
+ export { type ExactOptional, toExactOptional } from './to-exact-optional.ts';
@@ -0,0 +1,3 @@
1
+ export function isRecord(value: unknown): value is Record<string, unknown> {
2
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
3
+ }
@@ -0,0 +1,30 @@
1
+ // The keys whose value type admits undefined, an optional key among them.
2
+ type UndefinedKeys<T> = {
3
+ [K in keyof T]-?: undefined extends T[K] ? K : never;
4
+ }[keyof T];
5
+
6
+ // Flattens an intersection into one object type, so editors show its keys.
7
+ type Simplify<T> = { [K in keyof T]: T[K] };
8
+
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
+ export type ExactOptional<T extends object> = T extends unknown
13
+ ? Simplify<
14
+ Pick<T, Exclude<keyof T, UndefinedKeys<T>>> & {
15
+ [K in keyof Pick<T, UndefinedKeys<T>>]?: Exclude<T[K], undefined>;
16
+ }
17
+ >
18
+ : never;
19
+
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
+ export function toExactOptional<T extends object>(value: T): ExactOptional<T> {
23
+ const entries = Reflect.ownKeys(value)
24
+ .filter((key) => Object.prototype.propertyIsEnumerable.call(value, key))
25
+ .map((key): [PropertyKey, unknown] => [key, Reflect.get(value, key)])
26
+ .filter(([, entry]) => entry !== undefined);
27
+
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
29
+ return Object.fromEntries(entries) as ExactOptional<T>;
30
+ }