@fgv/ts-utils 5.0.2 → 5.1.0-0

package/README.md

@@ -1,132 +1,200 @@
-<div align="center">
-  <h1>ts-utils</h1>
-  Assorted Typescript Utilities
-</div>
+# @fgv/ts-utils
 
-<hr/>
-
-## Summary
-
-Assorted typescript utilities that I'm tired of copying from project to project. Most notable and closest to production-ready are:
-* Result\<T\> - Easily combine inline and exception-based error handling
-* Converter\<T\> - Conversion framework especially useful for type-safe processing of JSON
-
----
-
-- [Summary](#summary)
-- [Installation](#installation)
-- [API Documentation](#api-documentation)
-- [Overview](#overview)
-  - [The Result Pattern](#the-result-pattern)
-  - [Converters](#converters)
-- [API](#api)
-  - [Result\<T\>](#resultt)
-  - [Converter\<T\>](#convertert)
+Type-safe utilities for TypeScript — Result pattern, composable converters and validators, and Result-aware collections.
 
 ## Installation
 
-With npm:
 ```sh
 npm install @fgv/ts-utils
 ```
 
-## API Documentation
-Extracted API documentation is [here](./docs/ts-utils.md).
-
 ## Overview
-### The Result Pattern
 
-A Result\<T\> represents the success or failure of executing some operation.  A successful result contains a return *value* of type *T*, while a failure result contains an error message of type *string*.  Taken by itself, the use of Result\<T\> allows for simple inline error handling.
+`@fgv/ts-utils` provides a cohesive set of utilities built around the Result pattern. Instead of throwing exceptions for expected error conditions, all fallible operations return `Result<T>` — making errors explicit in the type system and enabling safe, composable error handling.
+
+The library is organized into six packlets, each with its own detailed documentation.
+
+## The Result Pattern
+
+A `Result<T>` is either a `Success<T>` containing a value, or a `Failure<T>` containing an error message. This replaces exception-based error handling with explicit, chainable results.
+
+### Creating Results
 
-```ts
-const result = functionReturningResult();
-if (result.isSuccess()) {
-    functionAcceptingT(result.value);
+```typescript
+import { Result, succeed, fail, captureResult } from '@fgv/ts-utils';
+
+function divide(a: number, b: number): Result<number> {
+  if (b === 0) {
+    return fail('Division by zero');
+  }
+  return succeed(a / b);
 }
-else {
-    console.log(result.error);
+
+// Wrap throwing code
+function parseJson(text: string): Result<unknown> {
+  return captureResult(() => JSON.parse(text));
 }
 ```
 
-Use *succeed\<T>()* and *fail\<T\>()* to return success or failure:
+### Extracting Values
 
-```ts
-function thisFunctionSucceeds(): string {
-    return succeed('I succeeded!');
-}
+```typescript
+// In setup/initialization — converts failure to exception
+const config = loadConfig().orThrow();
+
+// Safe fallback
+const port = getPort().orDefault(3000);
+```
+
+### Chaining Operations
 
-function thisFunctionFails(): number {
-    return fail('Oops!  I failed');
+```typescript
+function processData(input: string): Result<ProcessedData> {
+  return parseInput(input)
+    .onSuccess((parsed) => validate(parsed))
+    .onSuccess((valid) => transform(valid));
 }
 ```
 
-Use *orDefault* when a failure can be safely ignored:
-```ts
-// returns undefined on failure
-const value1: string|undefined = functionReturningResult('whatever').orDefault();
+### Error Context
 
-// returns 'oops' on failure
-const value2: string = functionReturningResult('whatever').orDefault('oops');
+```typescript
+function loadUser(id: string): Result<User> {
+  return fetchUser(id)
+    .withErrorFormat((msg) => `Failed to load user ${id}: ${msg}`);
+}
 ```
 
-The *orThrow* method converts a failure result to an exception, for use in contexts (such as constructors) in which an exception is the most appropriate way to handle errors.
+### Error Aggregation
+
+```typescript
+import { mapResults, MessageAggregator } from '@fgv/ts-utils';
+
+// Aggregate array of results
+const results = items.map((item) => processItem(item));
+return mapResults(results); // All must succeed, or errors are aggregated
 
-```ts
-constructor(param: string) {
-    this._param = validateReturnsResult(param).orThrow();
+// Collect errors manually
+const aggregator = new MessageAggregator();
+validateA(data).aggregateError(aggregator);
+validateB(data).aggregateError(aggregator);
+if (aggregator.hasMessages) {
+  return fail(aggregator.toString('; '));
 }
 ```
 
-The *captureResult* function converts an exception to a failure for simplified inline processing.
+### Factory Pattern
 
-```ts
-class Thing {
-    static create(param: string): Result<Thing> {
-        return captureResult(new Thing(param));
-    }
+```typescript
+class ResourceManager {
+  private constructor(private config: Config) { /* may throw */ }
+
+  public static create(params: Params): Result<ResourceManager> {
+    return validateParams(params)
+      .onSuccess((valid) => loadConfig(valid))
+      .onSuccess((config) => captureResult(() => new ResourceManager(config)));
+  }
 }
 ```
 
-Other methods and helpers allow for chaining and conversion of results, working with mulitple results and more.  See the [API documentation](#resultt) for details.
+### Best Practices
+
+- Return `Result<T>` from fallible operations — never throw in business logic
+- Use `orThrow()` only in setup/initialization
+- Prefer chaining over intermediate variables
+- Add context with `withErrorFormat()` as errors propagate
+- Use `MessageAggregator` for collecting multiple errors
 
-### Converters
+[Full Result pattern documentation &rarr;](./src/packlets/base/README.md)
 
-The basic *Converter\<T\>* implements a *convert* method which converts *unknown* to *T*, using the result pattern to report success or failure.
+## Type-Safe Conversion
 
-```ts
-class Converter<T> {
-    public convert(from: unknown): Result<T>;
+`Converter<T>` converts `unknown` to `T`, returning `Result<T>`. Converters compose to build type-safe pipelines for JSON parsing and data transformation.
+
+```typescript
+import { Converters } from '@fgv/ts-utils';
+
+interface IConfig {
+  host: string;
+  port: number;
+  debug: boolean;
+  tags: string[];
 }
+
+const configConverter = Converters.object<IConfig>({
+  host: Converters.string,
+  port: Converters.number,
+  debug: Converters.boolean,
+  tags: Converters.arrayOf(Converters.string),
+});
+
+const config = configConverter.convert(json).orThrow();
 ```
 
-But built-in converters, including converters which can extract a field for an object or which apply converters according to the shape of some object can be composed to provide compact and legible type-safe conversion from anything to a strongly typed Typescript object:
+Converters support a fluent modifier API:
 
-```ts
-interface Thing {
-    title: string;
-    count: number;
-    isGood: boolean;
-    hints: string[];
-}
+```typescript
+Converters.number
+  .withConstraint((n) => n > 0 && n < 65536, { description: 'valid port' })
+  .withBrand<'Port'>('Port');
+```
+
+[Full conversion documentation &rarr;](./src/packlets/conversion/README.md)
+
+## In-Place Validation
+
+`Validator<T>` verifies a value is of type `T` without creating a new object — preserving object identity and prototype chains.
+
+```typescript
+import { Validators } from '@fgv/ts-utils';
 
-const thingConverter = Converters.object<Thing>({
-    title: Converters.string,
-    count: Converters.number,
-    isGood: Converters.boolean,
-    hints: Converters.array(Converters.string),
+const userValidator = Validators.object<IUser>({
+  name: Validators.string,
+  age: Validators.number,
+  active: Validators.boolean,
 });
 
-// gets a Thing or throws an error
-const thing: Things = thingConverter.convert(json).orThrow();
+const result = userValidator.validate(input); // Result<IUser>
 ```
 
-Everything is strongly-typed, so Intellisense will autocomplete properties and highlight errors in the object supplied to *Converters.object*.
+Converters and Validators interoperate — use either as field definitions in object converters.
 
-Other helpers and methods enable optional values or fields, chaining of results and a variety of other conversions and transformations.
+[Full validation documentation &rarr;](./src/packlets/validation/README.md)
 
-## API
+## Type-Safe Collections
 
-### Result\<T\>
+`ResultMap` provides a `Map`-like API where all operations return `DetailedResult` with discriminated details (`'added'`, `'exists'`, `'not-found'`, etc.):
 
-### Converter\<T\>
+```typescript
+import { ResultMap } from '@fgv/ts-utils';
 
+const map = new ResultMap<string, number>();
+map.add('key', 42);           // detail: 'added'
+map.add('key', 99);           // detail: 'exists' (failure)
+map.get('key');                // detail: 'exists', value: 42
+map.get('missing');            // detail: 'not-found' (failure)
+```
+
+The collections packlet also provides `Collector` (append-only with write-once indexing), `ValidatingResultMap` (weakly-typed access with validation), `ConvertingResultMap` (lazy conversion with caching), and `AggregatedResultMap` (multi-collection composite IDs).
+
+[Full collections documentation &rarr;](./src/packlets/collections/README.md)
+
+## Additional Utilities
+
+- **[Logging](./src/packlets/logging/README.md)** — Level-based logging with `ConsoleLogger`, `InMemoryLogger` (for testing), and `LogReporter` for Result-aware reporting.
+- **[Hashing](./src/packlets/hash/README.md)** — Deterministic hashing of nested objects with `Crc32Normalizer`, producing consistent hashes regardless of property order.
+
+## Packlet Reference
+
+| Packlet | Description | Documentation |
+|---------|-------------|---------------|
+| `base` | Result pattern, error aggregation, branded types | [README](./src/packlets/base/README.md) |
+| `conversion` | Type-safe converters (`unknown` &rarr; `T`) | [README](./src/packlets/conversion/README.md) |
+| `validation` | In-place validators (verify without transforming) | [README](./src/packlets/validation/README.md) |
+| `collections` | Result-aware Map/Collection with validation layers | [README](./src/packlets/collections/README.md) |
+| `logging` | Level-based logging with Result integration | [README](./src/packlets/logging/README.md) |
+| `hash` | Deterministic object hashing | [README](./src/packlets/hash/README.md) |
+
+## API Documentation
+
+Extracted API documentation is [here](./docs/ts-utils.md).

package/dist/index.js

@@ -24,9 +24,9 @@ import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 import * as Logging from './packlets/logging';
 import * as Validation from './packlets/validation';
-import { Collector, ConvertingCollector, ResultMap, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
+import { AggregatedResultMap, Collector, ConvertingCollector, ResultMap, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
 import { Converters, ObjectConverter, StringConverter } from './packlets/conversion';
 import { Validators } from './packlets/validation';
 export * from './packlets/base';
-export { Collections, Collector, ConvertingCollector, Conversion, Converters, Hash, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validators };
+export { AggregatedResultMap, Collections, Collector, ConvertingCollector, Conversion, Converters, Hash, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validators };
 //# sourceMappingURL=index.js.map

package/dist/packlets/base/messageAggregator.js

@@ -36,25 +36,25 @@ export class MessageAggregator {
         this._messages = errors ? Array.from(errors) : [];
     }
     /**
-     * {@inheritdoc IMessageAggregator.hasMessages}
+     * {@inheritDoc IMessageAggregator.hasMessages}
      */
     get hasMessages() {
         return this._messages.length > 0;
     }
     /**
-     * {@inheritdoc IMessageAggregator.numMessages}
+     * {@inheritDoc IMessageAggregator.numMessages}
      */
     get numMessages() {
         return this._messages.length;
     }
     /**
-     * {@inheritdoc IMessageAggregator.messages}
+     * {@inheritDoc IMessageAggregator.messages}
      */
     get messages() {
         return this._messages;
     }
     /**
-     * {@inheritdoc IMessageAggregator.addMessage}
+     * {@inheritDoc IMessageAggregator.addMessage}
      */
     addMessage(message) {
         if (message) {
@@ -63,7 +63,7 @@ export class MessageAggregator {
         return this;
     }
     /**
-     * {@inheritdoc IMessageAggregator.addMessages}
+     * {@inheritDoc IMessageAggregator.addMessages}
      */
     addMessages(messages) {
         if (messages && messages.length > 0) {
@@ -72,7 +72,7 @@ export class MessageAggregator {
         return this;
     }
     /**
-     * {@inheritdoc IMessageAggregator.toString}
+     * {@inheritDoc IMessageAggregator.toString}
      */
     toString(separator) {
         return this._messages.join(separator !== null && separator !== void 0 ? separator : '\n');

package/dist/packlets/base/result.js

@@ -40,7 +40,7 @@ export class Success {
      */
     constructor(value) {
         /**
-         * {@inheritdoc IResult.success}
+         * {@inheritDoc IResult.success}
          */
         this.success = true;
         /**
@@ -56,13 +56,13 @@ export class Success {
         return this._value;
     }
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess() {
         return true;
     }
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure() {
         return false;
@@ -75,58 +75,58 @@ export class Success {
         return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
     }
     /**
-     * {@inheritdoc IResult.getValueOrThrow}
-     * @deprecated Use {@link Success.(orThrow:1) | orThrow(logger)} or {@link Success.(orThrow:2) | orThrow(formatter)} instead.
+     * {@inheritDoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Success.orThrow | orThrow(logger)} or {@link Success.orThrow | orThrow(formatter)} instead.
      */
     getValueOrThrow(__logger) {
         return this._value;
     }
     /**
-     * {@inheritdoc IResult.getValueOrDefault}
-     * @deprecated Use {@link Success.(orDefault:1) | orDefault(T)} or {@link Success.(orDefault:2) | orDefault()} instead.
+     * {@inheritDoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Success.orDefault | orDefault(T)} or {@link Success.orDefault | orDefault()} instead.
      */
     getValueOrDefault(dflt) {
         var _a;
         return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
     }
     /**
-     * {@inheritdoc IResult.onSuccess}
+     * {@inheritDoc IResult.onSuccess}
      */
     onSuccess(cb) {
         return cb(this._value);
     }
     /**
-     * {@inheritdoc IResult.onFailure}
+     * {@inheritDoc IResult.onFailure}
      */
     onFailure(__) {
         return this;
     }
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(__cb) {
         return this;
     }
     /**
-     * {@inheritdoc IResult.withFailureDetail}
+     * {@inheritDoc IResult.withFailureDetail}
      */
     withFailureDetail(__detail) {
         return succeedWithDetail(this._value);
     }
     /**
-     * {@inheritdoc IResult.withDetail}
+     * {@inheritDoc IResult.withDetail}
      */
     withDetail(detail, successDetail) {
         return succeedWithDetail(this._value, successDetail !== null && successDetail !== void 0 ? successDetail : detail);
     }
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(__errors, __formatter) {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a;
@@ -156,7 +156,7 @@ export class Failure {
      */
     constructor(message) {
         /**
-         * {@inheritdoc IResult.success}
+         * {@inheritDoc IResult.success}
          */
         this.success = false;
         /**
@@ -172,13 +172,13 @@ export class Failure {
         return this._message;
     }
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess() {
         return false;
     }
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure() {
         return true;
@@ -198,8 +198,8 @@ export class Failure {
         return dflt;
     }
     /**
-     * {@inheritdoc IResult.getValueOrThrow}
-     * @deprecated Use {@link Failure.(orThrow:1) | orThrow(logger)} or {@link Failure.(orThrow:2) | orThrow(formatter)} instead.
+     * {@inheritDoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Failure.orThrow | orThrow(logger)} or {@link Failure.orThrow | orThrow(formatter)} instead.
      */
     getValueOrThrow(logger) {
         if (logger !== undefined) {
@@ -208,44 +208,44 @@ export class Failure {
         throw new Error(this._message);
     }
     /**
-     * {@inheritdoc IResult.getValueOrDefault}
-     * @deprecated Use {@link Failure.(orDefault:1) | orDefault(T)} or {@link Failure.(orDefault:2) | orDefault()} instead.
+     * {@inheritDoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Failure.orDefault | orDefault(T)} or {@link Failure.orDefault | orDefault()} instead.
      */
     getValueOrDefault(dflt) {
         return dflt;
     }
     /**
-     * {@inheritdoc IResult.onSuccess}
+     * {@inheritDoc IResult.onSuccess}
      */
     onSuccess(__) {
         return new Failure(this._message);
     }
     /**
-     * {@inheritdoc IResult.onFailure}
+     * {@inheritDoc IResult.onFailure}
      */
     onFailure(cb) {
         return cb(this._message);
     }
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(cb) {
         return fail(cb(this._message));
     }
     /**
-     * {@inheritdoc IResult.withFailureDetail}
+     * {@inheritDoc IResult.withFailureDetail}
      */
     withFailureDetail(detail) {
         return failWithDetail(this._message, detail);
     }
     /**
-     * {@inheritdoc IResult.withDetail}
+     * {@inheritDoc IResult.withDetail}
      */
     withDetail(detail, __successDetail) {
         return failWithDetail(this._message, detail);
     }
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(errors, formatter) {
         const message = formatter ? formatter(this._message) : this._message;
@@ -253,7 +253,7 @@ export class Failure {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a, _b, _c;
@@ -294,7 +294,7 @@ export function succeed(value) {
     return new Success(value);
 }
 /**
- * {@inheritdoc succeed}
+ * {@inheritDoc succeed}
  * @public
  */
 export function succeeds(value) {
@@ -312,7 +312,7 @@ export function fail(message) {
     return new Failure(message);
 }
 /**
- * {@inheritdoc fail}
+ * {@inheritDoc fail}
  * @public
  */
 export function fails(message) {
@@ -378,7 +378,7 @@ export class DetailedSuccess extends Success {
      * Propagates this {@link DetailedSuccess}.
      * @remarks
      * Failure does not mutate return type so we can return this event directly.
-     * @param _cb - {@link DetailedFailureContinuation | Failure callback} to be called
+     * @param __cb - {@link DetailedFailureContinuation | Failure callback} to be called
      * on a {@link DetailedResult} in case of failure (ignored).
      * @returns `this`
      */
@@ -386,13 +386,13 @@ export class DetailedSuccess extends Success {
         return this;
     }
     /**
-     * {@inheritdoc Success.withErrorFormat}
+     * {@inheritDoc Success.withErrorFormat}
      */
     withErrorFormat(cb) {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a;
@@ -455,7 +455,7 @@ export class DetailedFailure extends Failure {
      * @remarks
      * Mutates the success type as the success callback would have, but does not
      * call the success callback.
-     * @param _cb - {@link DetailedSuccessContinuation | Success callback} to be called
+     * @param __cb - {@link DetailedSuccessContinuation | Success callback} to be called
      * on a {@link DetailedResult} in case of success (ignored).
      * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains
      * the error message and detail from this one.
@@ -473,13 +473,13 @@ export class DetailedFailure extends Failure {
         return cb(this._message, this._detail);
     }
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(cb) {
         return failWithDetail(cb(this._message, this._detail), this._detail);
     }
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(errors, formatter) {
         const message = formatter ? formatter(this._message, this._detail) : this._message;
@@ -487,7 +487,7 @@ export class DetailedFailure extends Failure {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a, _b;
@@ -548,7 +548,7 @@ export function succeedWithDetail(value, detail) {
     return new DetailedSuccess(value, detail);
 }
 /**
- * {@inheritdoc succeedWithDetail}
+ * {@inheritDoc succeedWithDetail}
  * @public
  */
 export function succeedsWithDetail(value, detail) {
@@ -569,7 +569,7 @@ export function failWithDetail(message, detail) {
     return new DetailedFailure(message, detail);
 }
 /**
- * {@inheritdoc failWithDetail}
+ * {@inheritDoc failWithDetail}
  * @public
  */
 export function failsWithDetail(message, detail) {