@guillaume-docquier/tools-ts 2.0.0 → 2.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/README.md +87 -0
- package/dist/Assert.d.ts +6 -0
- package/dist/Assert.js +14 -0
- package/dist/Assert.js.map +1 -1
- package/package.json +15 -15
package/README.md
CHANGED
|
@@ -1,3 +1,90 @@
|
|
|
1
1
|
# tools-ts
|
|
2
2
|
|
|
3
3
|
A collection of small typescript tools published to npm
|
|
4
|
+
|
|
5
|
+
## Exported Tools Overview
|
|
6
|
+
|
|
7
|
+
This package is a grab bag of focused TypeScript utilities. Use this README as the
|
|
8
|
+
orientation layer: it tells you which tool to reach for and when. The individual
|
|
9
|
+
modules contain the deeper API examples and implementation notes.
|
|
10
|
+
|
|
11
|
+
### Error Handling And Assertions
|
|
12
|
+
|
|
13
|
+
Use these tools when code needs to distinguish expected failures from broken
|
|
14
|
+
program assumptions.
|
|
15
|
+
|
|
16
|
+
| Export | What it is | Use it when |
|
|
17
|
+
| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
18
|
+
| `Result`, `Success`, `Failure` | A typed success/failure return shape plus helper constructors and guards. | You want expected failures to be returned and handled explicitly instead of thrown. Prefer this for recoverable application outcomes. |
|
|
19
|
+
| `Result.tryCatch` | A wrapper that converts thrown or rejected non-fatal errors into `Failure`. | You are calling code that may throw, especially third-party APIs, and want to bring it back into the `Result` flow. |
|
|
20
|
+
| `Assert` | Runtime assertion helpers that throw `AssertionError` and narrow TypeScript types. | TypeScript cannot express an invariant strongly enough, or test code needs a clear fatal assertion. |
|
|
21
|
+
| `AssertionError` | A fatal error for violated assumptions, with structured context. | A program invariant is broken and continuing would hide a bug or corrupt later state. Usually use `Assert` unless you need a custom assertion. |
|
|
22
|
+
| `FatalError` | Base fatal error class with an `isFatal` flag and structured context. | An error should crash or escape normal expected-error handling. Extend this for domain-specific fatal errors. |
|
|
23
|
+
| `Rethrow` | Helpers for catch blocks that should not swallow fatal errors. | You catch `unknown` but only intend to handle recoverable `Error` instances. |
|
|
24
|
+
| `NotImplementedError` | A fatal placeholder error with tracking context. | A code path intentionally exists before the feature is implemented, and the missing work should be traceable. |
|
|
25
|
+
| `isNodeJSError` | Type guard for Node-style `ErrnoException` properties on `Error`. | You need to inspect fields like `code`, `path`, `errno`, or `syscall` after catching a Node.js error. |
|
|
26
|
+
|
|
27
|
+
### Type And Value Guards
|
|
28
|
+
|
|
29
|
+
Use these tools at runtime boundaries: parsed JSON, environment variables,
|
|
30
|
+
external APIs, CLI input, local storage, or other unknown data.
|
|
31
|
+
|
|
32
|
+
| Export | What it is | Use it when |
|
|
33
|
+
| ------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
34
|
+
| `TypeGuard` | Small runtime guards for primitives, arrays, records, integers, and enum members. | You need non-throwing checks that also narrow types. |
|
|
35
|
+
| `getEnumKey` | Looks up the enum key associated with a value. | You have an enum value and need the more descriptive key for display, logs, or diagnostics. |
|
|
36
|
+
| `asArray` | Normalizes a single value or array into an array. | An API accepts both `T` and `T[]`, but downstream logic should iterate uniformly. |
|
|
37
|
+
|
|
38
|
+
### Utility Types
|
|
39
|
+
|
|
40
|
+
These exports are type-only helpers for common TypeScript modeling problems.
|
|
41
|
+
|
|
42
|
+
| Export | What it is | Use it when |
|
|
43
|
+
| ------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
44
|
+
| `ConstructorType` | A type for class constructors. | A function accepts a class and later uses `new` or `instanceof` against it. |
|
|
45
|
+
| `EnumKeyType`, `EnumValueType`, `EnumType` | Broad shapes for enum-like objects. | You are writing generic utilities that operate on TypeScript enums or const-object enums. |
|
|
46
|
+
| `Enumify` | Converts a const object into a union of its values. | A project avoids TypeScript `enum` but wants enum-like ergonomics from `as const` objects. |
|
|
47
|
+
| `ValueOf` | Produces a union of an object's value types. | You need the values of a lookup object as a type. |
|
|
48
|
+
| `Prettify` | Re-expands an object type for easier editor hovers. | Intersections or mapped types are correct but hard to read in tooling. |
|
|
49
|
+
| `OmitOverUnion` | Applies `Omit` distributively across union members. | Native `Omit` collapses a discriminated union in a way that loses member-specific fields. |
|
|
50
|
+
| `PartialProperties` | Makes selected object properties partial, not the whole object. | Only nested property objects should become partial while the parent shape stays required. |
|
|
51
|
+
| `Mutable` | Removes `readonly` from selected properties. | You have a narrow, deliberate mutation need. Avoid this unless there is no cleaner model. |
|
|
52
|
+
|
|
53
|
+
### Logging
|
|
54
|
+
|
|
55
|
+
Use the logging tools when an application or library needs structured logs with
|
|
56
|
+
consistent context, scopes, formatting, and redaction.
|
|
57
|
+
|
|
58
|
+
| Export | What it is | Use it when |
|
|
59
|
+
| --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `Logger` | The package logger facade, backed by LogTape, with root configuration and child scoped loggers. | Application code needs to configure sinks/context, or library code needs a logger that can be configured later by the host app. |
|
|
61
|
+
| `createConsoleLogSink` | Console sink factory with production-oriented defaults. | You need a ready-to-use console sink with JSON lines, non-blocking writes, and secret redaction by default. |
|
|
62
|
+
| `jsonLineFormatter` | Structured one-record-per-line log formatter. | Logs are going to production systems, aggregators, or files where machine parsing matters. |
|
|
63
|
+
| `prettyConsoleFormatter` | Human-readable console formatter with expandable structured context. | Local development needs readable console output. |
|
|
64
|
+
| `RECOMMENDED_LOG_REDACTION` | Default field redaction rules for common secrets. | You want a baseline set of credential and sensitive-field protections for logs. |
|
|
65
|
+
| `LogSink` | Type alias for supported logging sinks. | You are typing sink integrations or custom sink factories. |
|
|
66
|
+
| `LogContext` | Type for user-provided structured log context. | You attach serializable context to log calls or logger instances. |
|
|
67
|
+
| `LoggerContext` | Type for the final context shape passed to sinks and formatters. | You are writing a formatter or sink and need the logger-reserved `scopes` field. |
|
|
68
|
+
| `LogContextProvider` | Interface for dynamic context providers. | Log context changes over time, such as the active user, request, tenant, or job. |
|
|
69
|
+
|
|
70
|
+
### Runtime Utilities
|
|
71
|
+
|
|
72
|
+
Use these small utilities to keep common asynchronous and callback patterns
|
|
73
|
+
consistent.
|
|
74
|
+
|
|
75
|
+
| Export | What it is | Use it when |
|
|
76
|
+
| ----------------- | ----------------------------- | ------------------------------------------------------------------------------- |
|
|
77
|
+
| `setTimeoutAsync` | Promise-based timeout helper. | You want `await`-friendly delays that work in browser and Node environments. |
|
|
78
|
+
| `debounce` | Creates a debounced callback. | A repeated event should trigger work only after calls have settled for a delay. |
|
|
79
|
+
| `noop` | Synchronous no-op function. | You need a safe default callback that intentionally does nothing. |
|
|
80
|
+
| `asyncNoop` | Asynchronous no-op function. | You need a safe default async callback or hook that resolves immediately. |
|
|
81
|
+
|
|
82
|
+
### Measurement
|
|
83
|
+
|
|
84
|
+
Use these helpers for lightweight operational visibility, not for rigorous
|
|
85
|
+
benchmarking.
|
|
86
|
+
|
|
87
|
+
| Export | What it is | Use it when |
|
|
88
|
+
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
89
|
+
| `Measure.executionTime` | Wraps sync or async work and logs elapsed time. | You need quick timing instrumentation around a named operation. |
|
|
90
|
+
| `Measure.memoryUsage` | Logs process memory usage in megabytes. | You need a snapshot of Node.js process memory for diagnostics or runtime visibility. |
|
package/dist/Assert.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { EnumType, ConstructorType } from "./utility-types.js";
|
|
2
|
+
import { Result, Success } from "./Result.js";
|
|
2
3
|
/**
|
|
3
4
|
* From Wikipedia
|
|
4
5
|
* In computer programming, [...] an assertion is a predicate connected to a point in the program, that always should evaluate to true at that point in code execution.
|
|
@@ -127,4 +128,9 @@ export declare class Assert {
|
|
|
127
128
|
* ```
|
|
128
129
|
*/
|
|
129
130
|
static isExhausted(this: void, value: never): asserts value is never;
|
|
131
|
+
/**
|
|
132
|
+
* Asserts that the Result is a success.
|
|
133
|
+
* This is mostly useful in tests, as real code should handle Failures.
|
|
134
|
+
*/
|
|
135
|
+
static isSuccess<T>(this: void, result: Result<T, unknown>, paramName?: string): asserts result is Success<T>;
|
|
130
136
|
}
|
package/dist/Assert.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { AssertionError } from "./errors/AssertionError.js";
|
|
2
2
|
import { TypeGuard } from "./TypeGuard.js";
|
|
3
|
+
import { Result } from "./Result.js";
|
|
3
4
|
/**
|
|
4
5
|
* From Wikipedia
|
|
5
6
|
* In computer programming, [...] an assertion is a predicate connected to a point in the program, that always should evaluate to true at that point in code execution.
|
|
@@ -175,6 +176,19 @@ export class Assert {
|
|
|
175
176
|
received: value,
|
|
176
177
|
}, Assert.isExhausted);
|
|
177
178
|
}
|
|
179
|
+
/**
|
|
180
|
+
* Asserts that the Result is a success.
|
|
181
|
+
* This is mostly useful in tests, as real code should handle Failures.
|
|
182
|
+
*/
|
|
183
|
+
static isSuccess(result, paramName) {
|
|
184
|
+
if (Result.isFailure(result)) {
|
|
185
|
+
throw new AssertionError("Expected result to be Success", {
|
|
186
|
+
paramName,
|
|
187
|
+
expected: "a Success",
|
|
188
|
+
received: `a Failure: ${formatPrimitiveValue(result.error)}`,
|
|
189
|
+
}, Assert.isSuccess);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
178
192
|
}
|
|
179
193
|
/**
|
|
180
194
|
* `quoteStrings` will put strings inside single quote for nicer output when you know the string will be nested inside a double quoted string
|
package/dist/Assert.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Assert.js","sourceRoot":"","sources":["../src/Assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;
|
|
1
|
+
{"version":3,"file":"Assert.js","sourceRoot":"","sources":["../src/Assert.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guillaume-docquier/tools-ts",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.1.1",
|
|
4
4
|
"description": "My personal collection of typescript tools",
|
|
5
5
|
"homepage": "https://github.com/Guillaume-Docquier/tools-ts",
|
|
6
6
|
"repository": {
|
|
@@ -47,30 +47,30 @@
|
|
|
47
47
|
"semi": false
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
|
-
"@logtape/logtape": "^2.
|
|
51
|
-
"@logtape/redaction": "^2.
|
|
50
|
+
"@logtape/logtape": "^2.1.1",
|
|
51
|
+
"@logtape/redaction": "^2.1.1"
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
54
|
"@eslint/js": "^10.0.1",
|
|
55
55
|
"@semantic-release/commit-analyzer": "^13.0.1",
|
|
56
|
-
"@semantic-release/github": "^12.0.
|
|
56
|
+
"@semantic-release/github": "^12.0.8",
|
|
57
57
|
"@semantic-release/npm": "^13.1.5",
|
|
58
|
-
"@semantic-release/release-notes-generator": "^14.1.
|
|
59
|
-
"@types/node": "^25.
|
|
60
|
-
"@vitest/coverage-v8": "^4.1.
|
|
61
|
-
"conventional-changelog-conventionalcommits": "^9.3.
|
|
62
|
-
"eslint": "^10.
|
|
58
|
+
"@semantic-release/release-notes-generator": "^14.1.1",
|
|
59
|
+
"@types/node": "^25.9.1",
|
|
60
|
+
"@vitest/coverage-v8": "^4.1.7",
|
|
61
|
+
"conventional-changelog-conventionalcommits": "^9.3.1",
|
|
62
|
+
"eslint": "^10.4.0",
|
|
63
63
|
"husky": "^9.1.7",
|
|
64
|
-
"jiti": "^2.
|
|
64
|
+
"jiti": "^2.7.0",
|
|
65
65
|
"lint-staged": "^16.4.0",
|
|
66
|
-
"prettier": "^3.8.
|
|
66
|
+
"prettier": "^3.8.3",
|
|
67
67
|
"semantic-release": "^25.0.3",
|
|
68
68
|
"sort-package-json": "^3.6.1",
|
|
69
|
-
"typescript": "
|
|
70
|
-
"typescript-eslint": "^8.
|
|
71
|
-
"vitest": "^4.1.
|
|
69
|
+
"typescript": "~6.0.3",
|
|
70
|
+
"typescript-eslint": "^8.59.4",
|
|
71
|
+
"vitest": "^4.1.7"
|
|
72
72
|
},
|
|
73
|
-
"packageManager": "pnpm@
|
|
73
|
+
"packageManager": "pnpm@11.3.0+sha512.2c403d6594527287672b1f7056343a1f7c3634036a67ffabfcc2b3d7595d843768f8787148d1b57cf7956c90606bbd192857c363af19e96d2d0ec9ec5741d215",
|
|
74
74
|
"publishConfig": {
|
|
75
75
|
"access": "public",
|
|
76
76
|
"provenance": true
|