@fgv/ts-utils 5.0.2 → 5.1.0-0

package/lib/packlets/base/result.js

@@ -55,7 +55,7 @@ class Success {
      */
     constructor(value) {
         /**
-         * {@inheritdoc IResult.success}
+         * {@inheritDoc IResult.success}
          */
         this.success = true;
         /**
@@ -71,13 +71,13 @@ class Success {
         return this._value;
     }
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess() {
         return true;
     }
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure() {
         return false;
@@ -90,58 +90,58 @@ 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;
@@ -172,7 +172,7 @@ class Failure {
      */
     constructor(message) {
         /**
-         * {@inheritdoc IResult.success}
+         * {@inheritDoc IResult.success}
          */
         this.success = false;
         /**
@@ -188,13 +188,13 @@ class Failure {
         return this._message;
     }
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess() {
         return false;
     }
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure() {
         return true;
@@ -214,8 +214,8 @@ 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) {
@@ -224,44 +224,44 @@ 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;
@@ -269,7 +269,7 @@ class Failure {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a, _b, _c;
@@ -311,7 +311,7 @@ function succeed(value) {
     return new Success(value);
 }
 /**
- * {@inheritdoc succeed}
+ * {@inheritDoc succeed}
  * @public
  */
 function succeeds(value) {
@@ -329,7 +329,7 @@ function fail(message) {
     return new Failure(message);
 }
 /**
- * {@inheritdoc fail}
+ * {@inheritDoc fail}
  * @public
  */
 function fails(message) {
@@ -395,7 +395,7 @@ 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`
      */
@@ -403,13 +403,13 @@ 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;
@@ -473,7 +473,7 @@ 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.
@@ -491,13 +491,13 @@ 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;
@@ -505,7 +505,7 @@ class DetailedFailure extends Failure {
         return this;
     }
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter, options) {
         var _a, _b;
@@ -567,7 +567,7 @@ function succeedWithDetail(value, detail) {
     return new DetailedSuccess(value, detail);
 }
 /**
- * {@inheritdoc succeedWithDetail}
+ * {@inheritDoc succeedWithDetail}
  * @public
  */
 function succeedsWithDetail(value, detail) {
@@ -588,7 +588,7 @@ function failWithDetail(message, detail) {
     return new DetailedFailure(message, detail);
 }
 /**
- * {@inheritdoc failWithDetail}
+ * {@inheritDoc failWithDetail}
  * @public
  */
 function failsWithDetail(message, detail) {

package/lib/packlets/base/utils.d.ts

@@ -27,6 +27,48 @@ export declare function pick<T extends object, K extends keyof T>(from: T, inclu
  * @public
  */
 export declare function omit<T extends object, K extends keyof T>(from: T, exclude: K[]): Omit<T, K>;
+/**
+ * Type-safe(ish) key extractor for typed records.
+ * @param obj - The record from which keys are to be extracted.
+ * @returns The keys of the record as an array.
+ * @public
+ */
+export declare function keysForRecord<TK extends string>(obj: Record<TK, unknown>): TK[];
+/**
+ * Type-safe(ish) value extractor for typed records.
+ * @param obj - The record from which values are to be extracted.
+ * @returns The values of the record as an array.
+ * @public
+ */
+export declare function valuesForRecord<TK extends string, TV>(obj: Record<TK, TV>): TV[];
+/**
+ * Type-safe(ish) entries extractor for typed records.
+ * @param obj - The record from which entries are to be extracted.
+ * @returns The entries of the record as an array of `[key, value]` tuples.
+ * @public
+ */
+export declare function entriesForRecord<TK extends string, TV>(obj: Record<TK, TV>): Array<[TK, TV]>;
+/**
+ * Type-safe(ish) record constructor from an iterable of `[key, value]` tuples.
+ * @param entries - The iterable of `[key, value]` tuples from which to construct the record.
+ * @returns A record constructed from the supplied entries.
+ * @public
+ */
+export declare function recordFromEntries<TK extends string, TV>(entries: Iterable<[TK, TV]>): Record<TK, TV>;
+/**
+ * Helper type to extract the element type and preserve readonly status.
+ * @public
+ */
+export type EnsureArrayResult<T> = T extends readonly (infer _U)[] ? T : T[];
+/**
+ * Ensures the input is an array. If already an array, returns it as-is.
+ * If a single item, wraps it in an array.
+ * Preserves readonly status of input arrays.
+ * @param items - A single item or an array of items.
+ * @returns The input array unchanged, or a new array containing the single item.
+ * @public
+ */
+export declare function ensureArray<T>(items: T): EnsureArrayResult<T>;
 /**
  * Gets the value of a property specified by key from an arbitrary object,
  * or a default value if the property does not exist.

package/lib/packlets/base/utils.js

@@ -24,6 +24,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isKeyOf = isKeyOf;
 exports.pick = pick;
 exports.omit = omit;
+exports.keysForRecord = keysForRecord;
+exports.valuesForRecord = valuesForRecord;
+exports.entriesForRecord = entriesForRecord;
+exports.recordFromEntries = recordFromEntries;
+exports.ensureArray = ensureArray;
 exports.getValueOfPropertyOrDefault = getValueOfPropertyOrDefault;
 exports.getTypeOfProperty = getTypeOfProperty;
 exports.recordToMap = recordToMap;
@@ -77,6 +82,53 @@ function omit(from, exclude) {
     }
     return rtrn;
 }
+/**
+ * Type-safe(ish) key extractor for typed records.
+ * @param obj - The record from which keys are to be extracted.
+ * @returns The keys of the record as an array.
+ * @public
+ */
+function keysForRecord(obj) {
+    return Object.keys(obj);
+}
+/**
+ * Type-safe(ish) value extractor for typed records.
+ * @param obj - The record from which values are to be extracted.
+ * @returns The values of the record as an array.
+ * @public
+ */
+function valuesForRecord(obj) {
+    return Object.values(obj);
+}
+/**
+ * Type-safe(ish) entries extractor for typed records.
+ * @param obj - The record from which entries are to be extracted.
+ * @returns The entries of the record as an array of `[key, value]` tuples.
+ * @public
+ */
+function entriesForRecord(obj) {
+    return Object.entries(obj);
+}
+/**
+ * Type-safe(ish) record constructor from an iterable of `[key, value]` tuples.
+ * @param entries - The iterable of `[key, value]` tuples from which to construct the record.
+ * @returns A record constructed from the supplied entries.
+ * @public
+ */
+function recordFromEntries(entries) {
+    return Object.fromEntries(entries);
+}
+/**
+ * Ensures the input is an array. If already an array, returns it as-is.
+ * If a single item, wraps it in an array.
+ * Preserves readonly status of input arrays.
+ * @param items - A single item or an array of items.
+ * @returns The input array unchanged, or a new array containing the single item.
+ * @public
+ */
+function ensureArray(items) {
+    return (Array.isArray(items) ? items : [items]);
+}
 /**
  * Gets the value of a property specified by key from an arbitrary object,
  * or a default value if the property does not exist.