@fgv/ts-utils 5.1.0-3 → 5.1.0-31

package/README.md

@@ -56,6 +56,27 @@ function processData(input: string): Result<ProcessedData> {
 }
 ```
 
+### Async Chaining
+
+Use `thenOnSuccess()` to chain async operations without breaking the fluent style:
+
+```typescript
+import { Result, succeed, captureAsyncResult } from '@fgv/ts-utils';
+
+async function processData(input: string): Promise<Result<SavedData>> {
+  return parseInput(input)
+    .onSuccess((parsed) => validate(parsed))
+    .thenOnSuccess(async (valid) => fetchRelatedData(valid.id))
+    .onSuccess((data) => transform(data))
+    .thenOnSuccess(async (transformed) => saveData(transformed))
+    .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+}
+```
+
+`AsyncResult<T>` implements `PromiseLike`, so the entire chain can be directly `await`ed. Rejected promises are caught and converted to `Failure`.
+
+[Full async chaining documentation &rarr;](./src/packlets/base/README.md#async-result-chaining)
+
 ### Error Context
 
 ```typescript

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,SAAS,EAET,mBAAmB,EAEnB,SAAS,EACT,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAa,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAa,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,UAAU,EAEV,UAAU,EACV,IAAI,EAGJ,OAAO,EACP,eAAe,EACf,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACnB,UAAU,EAEV,UAAU,EACX,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Collections from './packlets/collections';\nimport * as Conversion from './packlets/conversion';\nimport * as Hash from './packlets/hash';\nimport * as Logging from './packlets/logging';\nimport * as Validation from './packlets/validation';\n\nimport {\n  AggregatedResultMap,\n  Collector,\n  ICollectible,\n  ConvertingCollector,\n  IReadOnlyResultMap,\n  ResultMap,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap\n} from './packlets/collections';\nimport { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';\nimport { Validator, Validators } from './packlets/validation';\n\nexport * from './packlets/base';\nexport {\n  AggregatedResultMap,\n  Collections,\n  Collector,\n  ConvertingCollector,\n  Conversion,\n  Converter,\n  Converters,\n  Hash,\n  ICollectible,\n  IReadOnlyResultMap,\n  Logging,\n  ObjectConverter,\n  ResultMap,\n  StringConverter,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap,\n  Validation,\n  Validator,\n  Validators\n};\n"]}

package/dist/packlets/base/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../../src/packlets/base/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2021 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Helper type to brand a simple type to prevent inappropriate use\n * @public\n */\n\nexport type Brand<T, B> = T & { __brand: B };\n"]}

package/dist/packlets/base/index.js

@@ -24,5 +24,7 @@ export * from './mapResults';
 export * from './messageAggregator';
 export { Normalizer } from './normalize';
 export * from './result';
+export * from './shouldNotFail';
 export * from './utils';
+export * from './uuid';
 //# sourceMappingURL=index.js.map

package/dist/packlets/base/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/base/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nexport * from './brand';\nexport * from './mapResults';\nexport * from './messageAggregator';\nexport { Normalizer } from './normalize';\nexport * from './result';\nexport * from './shouldNotFail';\nexport * from './utils';\nexport * from './uuid';\n"]}

package/dist/packlets/base/mapResults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapResults.js","sourceRoot":"","sources":["../../../src/packlets/base/mapResults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAKL,IAAI,EACJ,gBAAgB,EAChB,OAAO,EACR,MAAM,UAAU,CAAC;AAElB;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,OAA4B,EAC5B,gBAAqC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAQ,EAAE,CAAC;IAEzB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAwC,EACxC,MAAY,EACZ,gBAAqC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAQ,EAAE,CAAC;IAEzB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,OAA4B,EAC5B,gBAAqC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAQ,EAAE,CAAC;IAEzB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,OAA4B,EAC5B,gBAAqC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC5B,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,OAAkC,EAClC,YAAe,EACf,gBAAqC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAI,OAAgD;IAC9E,MAAM,MAAM,GAAsB,IAAI,iBAAiB,EAAE,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;AACzD,CAAC;AAuED,MAAM,UAAU,cAAc,CAC5B,YAAkC,EAClC,cAAuD,EACvD,gBAAqC;;IAErC,MAAM,OAAO,GAA6B,cAAc;QACtD,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;YAC7B,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE;YAC3B,CAAC,CAAC,cAAc;QAClB,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,KAAK,GAAG,EAAkC,CAAC;IACjD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAgB,KAAK,CAAC,IAAI,CAAC,MAAA,OAAO,CAAC,KAAK,mCAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAU,OAAO,CAAC,KAAK,CAAC,CAAC;IAElD,kEAAkE;IAClE,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;gBACvB,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC/B,IACE,OAAO,CAAC,iBAAiB,KAAK,IAAI;wBAClC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EACrF,CAAC;wBACD,SAAS;oBACX,CAAC;gBACH,CAAC;gBACD,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,uBAAuB,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,gBAAgB,aAAhB,gBAAgB,uBAAhB,gBAAgB,CAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC,KAAU,CAAC,CAAC;AAC7B,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { MessageAggregator } from './messageAggregator';\nimport {\n  DeferredResult,\n  DetailedResult,\n  IMessageAggregator,\n  Result,\n  fail,\n  isDeferredResult,\n  succeed\n} from './result';\n\n/**\n * Aggregates successful result values from a collection of {@link Result | Result<T>}.\n * @param results - The collection of {@link Result | Result<T>} to be mapped.\n * @param aggregatedErrors  - Optional string array to which any error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns  If all {@link Result | results} are successful, returns {@link Success} with an\n * array containing all returned values.  If any {@link Result | results} failed, returns\n * {@link Failure} with a concatenated summary of all error messages.\n * @public\n */\nexport function mapResults<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else {\n      errors.push(result.message);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},\n * optionally ignoring certain error details.\n * @param results - The collection of {@link DetailedResult | DetailedResult<T, TD>} to be mapped.\n * @param ignore - An array of error detail values (of type `<TD>`) that should be ignored.\n * @param aggregatedErrors  - Optional string array to which any non-ignorable error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns {@link Success} with an array containing all successful results if all results either\n * succeeded or returned error details listed in `ignore`.  If any results failed with details\n * that cannot be ignored, returns {@link Failure} with an concatenated summary of all non-ignorable\n * error messages.\n * @public\n */\nexport function mapDetailedResults<T, TD>(\n  results: Iterable<DetailedResult<T, TD>>,\n  ignore: TD[],\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else if (result.detail && !ignore.includes(result.detail)) {\n      errors.push(result.message);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates successful results from a a collection of {@link Result | Result<T>}.\n * @param results - An `Iterable` of {@link Result | Result<T>} from which success\n * results are to be aggregated.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns {@link Success} with an array of `<T>` if any results were successful. If\n * all {@link Result | results} failed, returns {@link Failure} with a concatenated\n * summary of all error messages.\n * @public\n */\nexport function mapSuccess<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else {\n      errors.push(result.message);\n    }\n  }\n\n  if (elements.length === 0 && errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates error messages from a collection of {@link Result | Result<T>}.\n * @param results - An iterable collection of {@link Result | Result<T>} for which\n * error messages are aggregated.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns An array of strings consisting of all error messages returned by\n * {@link Result | results} in the source collection. Ignores {@link Success}\n * results and returns an empty array if there were no errors.\n * @public\n */\nexport function mapFailures<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): string[] {\n  const errors: string[] = [];\n  for (const result of results) {\n    if (result.isFailure()) {\n      errors.push(result.message);\n      aggregatedErrors?.addMessage(result.message);\n    }\n  }\n  return errors;\n}\n\n/**\n * Determines if an iterable collection of {@link Result | Result<T>} were all successful.\n * @param results - The collection of {@link Result | Result<T>} to be tested.\n * @param successValue - The value to be returned if results are successful.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns Returns {@link Success} with `successValue` if all {@link Result | results} are successful.\n * If any are unsuccessful, returns {@link Failure} with a concatenated summary of the error\n * messages from all failed elements.\n * @public\n */\nexport function allSucceed<T>(\n  results: Iterable<Result<unknown>>,\n  successValue: T,\n  aggregatedErrors?: IMessageAggregator\n): Result<T> {\n  const errors: string[] = [];\n\n  if (results !== undefined) {\n    for (const result of results) {\n      if (result.isFailure()) {\n        errors.push(result.message);\n      }\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(successValue);\n}\n\n/**\n * Returns the first successful result from a collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>}.\n * @param results - The collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>} to be tested.\n * @returns The first successful result, or {@link Failure} with a concatenated summary of all error messages.\n * @public\n */\nexport function firstSuccess<T>(results: Iterable<Result<T> | DeferredResult<T>>): Result<T> {\n  const errors: MessageAggregator = new MessageAggregator();\n  for (const r of results) {\n    const result = isDeferredResult(r) ? r() : r;\n    if (result.isSuccess()) {\n      return result;\n    }\n    errors.addMessage(result.message);\n  }\n  return errors.returnOrReport(fail('no results found'));\n}\n\n/**\n * String-keyed record of initialization functions to be passed to {@link populateObject}\n * or {@link populateObject}.\n * @public\n */\nexport type FieldInitializers<T> = { [key in keyof T]: (state: Partial<T>) => Result<T[key]> };\n\n/**\n * Options for the {@link populateObject} function.\n * @public\n */\n\nexport interface PopulateObjectOptions<T> {\n  /**\n   * If present, specifies the order in which property values should\n   * be evaluated.  Any keys not listed are evaluated after all listed\n   * keys in indeterminate order.  If 'order' is not present, keys\n   * are evaluated in indeterminate order.\n   */\n  order?: (keyof T)[];\n\n  /**\n   * Specify handling of `undefined` values.  By default, successful\n   * `undefined` results are written to the result object.  If this value\n   * is `true` then `undefined` results are suppressed for all properties.\n   * If this value is an array of property keys then `undefined` results\n   * are suppressed for those properties only.\n   */\n  suppressUndefined?: boolean | (keyof T)[];\n}\n\n/**\n * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.\n * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a\n * concatenated list of all error messages.\n * @param initializers - An object with the shape of the target but with initializer functions for\n * each property.\n * @param options - An optional {@link PopulateObjectOptions | set of options} which\n * modify the behavior of this call.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * {@label WITH_OPTIONS}\n * @public\n */\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  options?: PopulateObjectOptions<T>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T>;\n\n/**\n * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.\n * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a\n * concatenated list of all error messages.\n * @param initializers - An object with the shape of the target but with initializer functions for\n * each property.\n * @param order - Optional order in which keys should be written.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @public\n * {@label WITH_ORDER}\n * @deprecated Pass {@link PopulateObjectOptions} instead.\n */\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  order: (keyof T)[] | undefined,\n  aggregatedErrors?: IMessageAggregator\n): Result<T>;\n\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  optionsOrOrder?: PopulateObjectOptions<T> | (keyof T)[],\n  aggregatedErrors?: IMessageAggregator\n): Result<T> {\n  const options: PopulateObjectOptions<T> = optionsOrOrder\n    ? Array.isArray(optionsOrOrder)\n      ? { order: optionsOrOrder }\n      : optionsOrOrder\n    : {};\n  const state = {} as { [key in keyof T]: T[key] };\n  const errors: string[] = [];\n  const keys: (keyof T)[] = Array.from(options.order ?? []);\n  const foundKeys = new Set<keyof T>(options.order);\n\n  // start with the supplied order then append anything else we find\n  for (const key in initializers) {\n    if (!foundKeys.has(key)) {\n      keys.push(key);\n      foundKeys.add(key);\n    }\n  }\n\n  for (const key of keys) {\n    if (initializers[key]) {\n      const result = initializers[key](state);\n      if (result.isSuccess()) {\n        if (result.value === undefined) {\n          if (\n            options.suppressUndefined === true ||\n            (Array.isArray(options.suppressUndefined) && options.suppressUndefined.includes(key))\n          ) {\n            continue;\n          }\n        }\n        state[key] = result.value;\n      } else {\n        errors.push(result.message);\n      }\n    } else {\n      errors.push(`populateObject: Key ${String(key)} is present but has no initializer`);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(state as T);\n}\n"]}

package/dist/packlets/base/messageAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageAggregator.js","sourceRoot":"","sources":["../../../src/packlets/base/messageAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA8B,IAAI,EAAE,MAAM,UAAU,CAAC;AAE5D;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAG5B;;;;;OAKG;IACH,YAAmB,MAAiB;QAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,OAA2B;QAC3C,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,WAAW,CAAC,QAA8B;QAC/C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,QAAQ,CAAC,SAAkB;QAChC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,IAAI,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACI,cAAc,CAAI,MAAiB,EAAE,SAAkB;QAC5D,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtD,OAAO,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,IAAI,CAAC,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACxC,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2024 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { IMessageAggregator, Result, fail } from './result';\n\n/**\n * A simple error aggregator to simplify collecting and reporting all errors in\n * a flow.\n * @public\n */\nexport class MessageAggregator implements IMessageAggregator {\n  private readonly _messages: string[];\n\n  /**\n   * Constructs a new {@link MessageAggregator | ErrorAggregator} with an\n   * optionally specified initial set of error messages.\n   * @param errors - optional array of errors to be included\n   * in the aggregation.\n   */\n  public constructor(errors?: string[]) {\n    this._messages = errors ? Array.from(errors) : [];\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.hasMessages}\n   */\n  public get hasMessages(): boolean {\n    return this._messages.length > 0;\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.numMessages}\n   */\n  public get numMessages(): number {\n    return this._messages.length;\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.messages}\n   */\n  public get messages(): string[] {\n    return this._messages;\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.addMessage}\n   */\n  public addMessage(message: string | undefined): this {\n    if (message) {\n      this._messages.push(message);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.addMessages}\n   */\n  public addMessages(messages: string[] | undefined): this {\n    if (messages && messages.length > 0) {\n      this._messages.push(...messages);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IMessageAggregator.toString}\n   */\n  public toString(separator?: string): string {\n    return this._messages.join(separator ?? '\\n');\n  }\n\n  /**\n   * If any error messages have been aggregated, returns\n   * {@link Failure | Failure<T>} with the aggregated\n   * messages concatenated using the optionally-supplied\n   * separator, or newline.   If the supplied {@link Result | Result<T>}\n   * contains an error message that has not already been aggregated,\n   * it will be included in the aggregated messages.\n   *\n   * If no error messages have been aggregated, returns\n   * the supplied {@link Result | Result<T>}.\n   * @param result - The {@link Result | Result<T>} to be returned\n   * if no messages have been aggregated.\n   * @param separator - Optional string separator used to construct\n   * the error message.\n   * @returns {@link Failure | Failure<T>} with an aggregated message\n   * if any error messages were collected, the supplied\n   * {@link Result | Result<T>} otherwise.\n   */\n  public returnOrReport<T>(result: Result<T>, separator?: string): Result<T> {\n    if (!this.hasMessages) {\n      return result;\n    }\n    if (!result.success) {\n      if (!this._messages.find((s) => s === result.message)) {\n        return fail([...this._messages, result.message].join(separator ?? '\\n'));\n      }\n    }\n    return fail(this.toString(separator));\n  }\n}\n"]}

package/dist/packlets/base/normalize.js

@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 import { mapResults } from './mapResults';
-import { fail, succeed } from './result';
+import { captureResult, fail, succeed } from './result';
 /**
  * Normalizes an arbitrary JSON object
  * @public
@@ -62,6 +62,59 @@ export class Normalizer {
         }
         return fail(`normalize: Unexpected type - cannot normalize '${typeof from}'`);
     }
+    /**
+     * Produces a stable, byte-identical JSON string following RFC 8785
+     * (JSON Canonicalization Scheme) key-ordering rules.
+     *
+     * Builds the output string directly rather than constructing an intermediate
+     * JS object, so integer-string keys (`"10"`, `"2"`) retain lexicographic
+     * order instead of being reordered numerically by the JS engine during
+     * `JSON.stringify`.
+     *
+     * @param from - Any JSON-compatible value (string, number, boolean, null,
+     *   plain object, or array). Fails for non-JSON types (Map, Set, Date,
+     *   RegExp, function, symbol, bigint, undefined).
+     * @returns `Result<string>` — the canonical JSON string, or a failure if
+     *   `from` contains non-serializable types.
+     * @public
+     */
+    canonicalize(from) {
+        return captureResult(() => this._canonicalizeRfc8785(from));
+    }
+    /**
+     * Recursively builds a byte-identical RFC 8785 JSON string.
+     * @throws For non-JSON-serializable types (non-finite numbers, Date, RegExp,
+     *   Map, Set, class instances, function, symbol, bigint, undefined).
+     *   Callers must wrap in captureResult.
+     */
+    _canonicalizeRfc8785(value) {
+        if (value === null)
+            return 'null';
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                throw new Error(`canonicalize: non-finite number (${value}) is not representable in JSON`);
+            }
+            return JSON.stringify(value);
+        }
+        if (typeof value === 'string')
+            return JSON.stringify(value);
+        if (Array.isArray(value)) {
+            return '[' + value.map((item) => this._canonicalizeRfc8785(item)).join(',') + ']';
+        }
+        if (typeof value === 'object') {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new Error(`canonicalize: cannot serialize non-plain object (${Object.prototype.toString.call(value)})`);
+            }
+            const obj = value;
+            const sortedKeys = Object.keys(obj).sort((k1, k2) => this._compareKeys(k1, k2));
+            const pairs = sortedKeys.map((k) => JSON.stringify(k) + ':' + this._canonicalizeRfc8785(obj[k]));
+            return '{' + pairs.join(',') + '}';
+        }
+        throw new Error(`canonicalize: cannot serialize value of type '${typeof value}'`);
+    }
     /**
      * Compares two property names from some object being normalized.
      * @param k1 - First key to be compared.

package/dist/packlets/base/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/packlets/base/normalize.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2021 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { mapResults } from './mapResults';\nimport { Result, captureResult, fail, succeed } from './result';\n\n/**\n * @internal\n */\nexport type Entry<T> = [string | number | symbol, T];\n\n/**\n * @internal\n */\nexport type ResultEntry<T> = [string | number | symbol, Result<T>];\n\n/**\n * Normalizes an arbitrary JSON object\n * @public\n */\nexport class Normalizer {\n  /**\n   * Normalizes the supplied value\n   *\n   * @param from - The value to be normalized\n   * @returns A normalized version of the value\n   */\n  public normalize<T>(from: T): Result<T> {\n    switch (typeof from) {\n      case 'string':\n      case 'bigint':\n      case 'boolean':\n      case 'number':\n      case 'symbol':\n      case 'undefined':\n        return this.normalizeLiteral(from);\n      case 'object':\n        if (from === null || from instanceof Date || from instanceof RegExp) {\n          return this.normalizeLiteral(from);\n        } else if (Array.isArray(from)) {\n          return this._normalizeArray(from) as unknown as Result<T>;\n        } else if (from instanceof Map) {\n          return succeed(new Map(this.normalizeEntries(from.entries())) as unknown as T);\n        } else if (from instanceof Set) {\n          return succeed(new Set(this.normalizeEntries(from.entries())) as unknown as T);\n        }\n        const obj: { [key in number | string | symbol]: unknown } = {};\n        for (const e of this.normalizeEntries(Object.entries(from as unknown as object))) {\n          obj[e[0]] = e[1];\n        }\n        return succeed(obj as T);\n    }\n    return fail(`normalize: Unexpected type - cannot normalize '${typeof from}'`);\n  }\n\n  /**\n   * Produces a stable, byte-identical JSON string following RFC 8785\n   * (JSON Canonicalization Scheme) key-ordering rules.\n   *\n   * Builds the output string directly rather than constructing an intermediate\n   * JS object, so integer-string keys (`\"10\"`, `\"2\"`) retain lexicographic\n   * order instead of being reordered numerically by the JS engine during\n   * `JSON.stringify`.\n   *\n   * @param from - Any JSON-compatible value (string, number, boolean, null,\n   *   plain object, or array). Fails for non-JSON types (Map, Set, Date,\n   *   RegExp, function, symbol, bigint, undefined).\n   * @returns `Result<string>` — the canonical JSON string, or a failure if\n   *   `from` contains non-serializable types.\n   * @public\n   */\n  public canonicalize(from: unknown): Result<string> {\n    return captureResult(() => this._canonicalizeRfc8785(from));\n  }\n\n  /**\n   * Recursively builds a byte-identical RFC 8785 JSON string.\n   * @throws For non-JSON-serializable types (non-finite numbers, Date, RegExp,\n   *   Map, Set, class instances, function, symbol, bigint, undefined).\n   *   Callers must wrap in captureResult.\n   */\n  protected _canonicalizeRfc8785(value: unknown): string {\n    if (value === null) return 'null';\n    if (typeof value === 'boolean') return value ? 'true' : 'false';\n    if (typeof value === 'number') {\n      if (!Number.isFinite(value)) {\n        throw new Error(`canonicalize: non-finite number (${value}) is not representable in JSON`);\n      }\n      return JSON.stringify(value);\n    }\n    if (typeof value === 'string') return JSON.stringify(value);\n    if (Array.isArray(value)) {\n      return '[' + value.map((item) => this._canonicalizeRfc8785(item)).join(',') + ']';\n    }\n    if (typeof value === 'object') {\n      const proto = Object.getPrototypeOf(value as object) as unknown;\n      if (proto !== Object.prototype && proto !== null) {\n        throw new Error(\n          `canonicalize: cannot serialize non-plain object (${Object.prototype.toString.call(value)})`\n        );\n      }\n      const obj = value as Record<string, unknown>;\n      const sortedKeys = Object.keys(obj).sort((k1, k2) => this._compareKeys(k1, k2));\n      const pairs = sortedKeys.map((k) => JSON.stringify(k) + ':' + this._canonicalizeRfc8785(obj[k]));\n      return '{' + pairs.join(',') + '}';\n    }\n    throw new Error(`canonicalize: cannot serialize value of type '${typeof value}'`);\n  }\n\n  /**\n   * Compares two property names from some object being normalized.\n   * @param k1 - First key to be compared.\n   * @param k2 - Second key to be compared.\n   * @returns `1` if `k1` is greater, `-1` if `k2` is greater and\n   * `0` if they are equal.\n   * @internal\n   */\n  protected _compareKeys(k1: unknown, k2: unknown): number {\n    const cs1 = String(k1);\n    const cs2 = String(k2);\n    if (cs1 > cs2) {\n      return 1;\n    }\n    if (cs2 > cs1) {\n      return -1;\n    }\n    /* c8 ignore next 2 */\n    return 0;\n  }\n\n  /**\n   * Normalizes an array of object property entries (e.g. as returned by `Object.entries()`).\n   * @remarks\n   * Converts property names (entry key) to string and then sorts as string.\n   * @param entries - The entries to be normalized.\n   * @returns A normalized sorted array of entries.\n   */\n  public normalizeEntries<T = unknown>(entries: Iterable<Entry<T>>): Entry<T>[] {\n    return Array.from(entries)\n      .sort((e1, e2) => this._compareKeys(e1[0], e2[0]))\n      .map((e) => [e[0], this.normalize(e[1])] as ResultEntry<T>)\n      .filter((e) => e[1].isSuccess())\n      .map((e) => [e[0], e[1].orThrow()]);\n  }\n\n  protected _normalizeArray(from: unknown[]): Result<unknown[]> {\n    return mapResults(from.map((v) => this.normalize(v)));\n  }\n\n  /**\n   * Normalizes the supplied literal value\n   * @param from - The literal value to be normalized.\n   * @returns A normalized value for the literal.\n   */\n  public normalizeLiteral<T>(from: T): Result<T> {\n    // TODO: Apply configurable normalization rules\n    switch (typeof from) {\n      case 'string':\n        return succeed(from);\n      case 'bigint':\n      case 'boolean':\n      case 'number':\n      case 'symbol':\n      case 'undefined':\n        return succeed(from);\n    }\n    if (from === null) {\n      return succeed(from);\n    }\n    if (from instanceof Date) {\n      return succeed(from);\n    }\n    if (from instanceof RegExp) {\n      return succeed(from);\n    }\n    /* c8 ignore next 2 */\n    return fail(`cannot normalize ${JSON.stringify(from)}`);\n  }\n}\n"]}

package/dist/packlets/base/result.js

@@ -19,6 +19,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+import { _findShouldNotFailFrame, _formatShouldNotFailMessage } from './shouldNotFail';
 /**
  * Checks if a result is a deferred result.
  * @param result - The result to check.
@@ -70,6 +71,12 @@ export class Success {
     orThrow(__logger) {
         return this._value;
     }
+    /**
+     * {@inheritDoc IResult.shouldNotFail}
+     */
+    shouldNotFail(__label, __frameDepth) {
+        return this._value;
+    }
     orDefault(dflt) {
         var _a;
         return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
@@ -101,6 +108,26 @@ export class Success {
     onFailure(__) {
         return this;
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._value));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(this);
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -194,6 +221,32 @@ export class Failure {
         }
         throw new Error(this._message);
     }
+    /**
+     * {@inheritDoc IResult.shouldNotFail}
+     */
+    shouldNotFail(label, frameDepth = 1) {
+        // Parse a probe Error's stack to identify the caller frame for message
+        // composition. We must NOT reuse this probe as the thrown Error: in V8,
+        // `.stack` is materialized lazily on first access (which happens below in
+        // `_findShouldNotFailFrame`), and once materialized the cached stack
+        // header carries whatever message was set at that moment. Mutating
+        // `.message` afterwards does not refresh the cached `.stack` header.
+        const probe = new Error();
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(probe, this.shouldNotFail);
+        }
+        const frame = _findShouldNotFailFrame(probe.stack, frameDepth);
+        const message = _formatShouldNotFailMessage(this._message, label, frame);
+        // Build the final Error with the formatted message and re-elide
+        // `shouldNotFail` from its stack, so the thrown error's `.stack` shows
+        // both the formatted message in its header and the caller as its top
+        // frame.
+        const err = new Error(message);
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(err, this.shouldNotFail);
+        }
+        throw err;
+    }
     orDefault(dflt) {
         return dflt;
     }
@@ -226,6 +279,26 @@ export class Failure {
     onFailure(cb) {
         return cb(this._message);
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(fail(this._message));
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._message));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -263,6 +336,45 @@ export class Failure {
         reporter === null || reporter === void 0 ? void 0 : reporter.reportFailure(level, message);
         return this;
     }
+    /**
+     * Re-types this {@link Failure | Failure<T>} as {@link Failure | Failure<U>} for
+     * propagation under a different success type.
+     * @remarks
+     * Supports the canonical Result early-return-after-`isFailure()` pattern when the
+     * outer function's success type differs from the inner Result's success type:
+     *
+     * ```ts
+     * const storeResult = await PromptStoreFixture.build(seed);
+     * if (storeResult.isFailure()) {
+     *   return storeResult.withType<PromptLibrary>();
+     * }
+     * return PromptLibrary.create({ store: storeResult.value, ... });
+     * ```
+     *
+     * Without this helper, TypeScript rejects `return storeResult` because
+     * `Failure<IPromptStore>` is invariant in `T` and not assignable to
+     * `Result<PromptLibrary>`. The workaround `return fail<U>(r.message)` is
+     * semantically equivalent but allocates a new {@link Failure} instance;
+     * `withType` returns `this` and only retypes statically.
+     *
+     * This method is sound because a {@link Failure} variant carries no `T`-shaped
+     * data — only an error message — so re-typing it as `Failure<U>` cannot
+     * misrepresent any value. The same operation is NOT exposed on {@link Success}
+     * because `Success<T>` carries `T`-shaped data and re-typing would be a lie.
+     *
+     * For `DetailedResult` propagation that preserves a typed `detail`, consider
+     * propagating the {@link DetailedFailure} directly through `onSuccess` (which
+     * already re-types the success arm) rather than reaching for `withType`.
+     *
+     * @returns This same {@link Failure} instance, statically retyped as
+     * {@link Failure | Failure<U>}.
+     * @public
+     */
+    withType() {
+        // Safe by construction: Failure carries no T-shaped data, only a message.
+        // Re-typing the static T parameter cannot misrepresent any value.
+        return this;
+    }
     /**
      * Get a 'friendly' string representation of this object.
      * @remarks
@@ -591,13 +703,25 @@ export function propagateWithDetail(result, detail, successDetail) {
         ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
         : failWithDetail(result.message, detail);
 }
+/**
+ * Extracts a message string from an unknown thrown/rejected value.
+ * @param err - The caught error value.
+ * @returns The error message string.
+ * @internal
+ */
+export function _errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 export function captureResult(func) {
@@ -605,7 +729,180 @@ export function captureResult(func) {
         return succeed(func());
     }
     catch (err) {
-        return fail(err.message);
+        return fail(_errorMessage(err));
+    }
+}
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+export class AsyncResult {
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise) {
+        this._promise = promise.catch((err) => fail(_errorMessage(err)));
+    }
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onSuccess(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isFailure()) {
+                return fail(r.message);
+            }
+            try {
+                return await cb(r.value);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onFailure(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isSuccess()) {
+                return r;
+            }
+            try {
+                return await cb(r.message);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb) {
+        return new AsyncResult(this._promise.then((r) => r.withErrorFormat(cb)));
+    }
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors, formatter) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.aggregateError(errors, formatter);
+            return r;
+        }));
+    }
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter, options) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.report(reporter, options);
+            return r;
+        }));
+    }
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    /* eslint-disable @rushstack/no-new-null */
+    then(onfulfilled, onrejected) {
+        /* eslint-enable @rushstack/no-new-null */
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from(result) {
+        return new AsyncResult(Promise.resolve(result));
+    }
+}
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+export async function captureAsyncResult(func) {
+    try {
+        return succeed(await func());
+    }
+    catch (err) {
+        return fail(_errorMessage(err));
     }
 }
 //# sourceMappingURL=result.js.map