@fgv/ts-utils 1.2.0 → 1.3.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.
Files changed (77) hide show
  1. package/LICENSE +0 -0
  2. package/README.md +4 -0
  3. package/brand.d.ts +8 -0
  4. package/brand.d.ts.map +1 -0
  5. package/brand.js +24 -0
  6. package/converter.d.ts +149 -105
  7. package/converter.d.ts.map +1 -0
  8. package/converter.js +59 -72
  9. package/converters.d.ts +432 -194
  10. package/converters.d.ts.map +1 -0
  11. package/converters.js +335 -224
  12. package/csvHelpers.d.ts +7 -0
  13. package/csvHelpers.d.ts.map +1 -0
  14. package/csvHelpers.js +14 -4
  15. package/extendedArray.d.ts +46 -0
  16. package/extendedArray.d.ts.map +1 -0
  17. package/extendedArray.js +53 -8
  18. package/formatter.d.ts +53 -0
  19. package/formatter.d.ts.map +1 -0
  20. package/formatter.js +27 -4
  21. package/hash.d.ts +51 -0
  22. package/hash.d.ts.map +1 -0
  23. package/hash.js +168 -0
  24. package/index.d.ts +7 -2
  25. package/index.d.ts.map +1 -0
  26. package/index.js +16 -5
  27. package/logger.d.ts +3 -2
  28. package/logger.d.ts.map +1 -0
  29. package/logger.js +12 -12
  30. package/package.json +24 -20
  31. package/rangeOf.d.ts +96 -0
  32. package/rangeOf.d.ts.map +1 -0
  33. package/rangeOf.js +81 -2
  34. package/result.d.ts +393 -39
  35. package/result.d.ts.map +1 -0
  36. package/result.js +259 -49
  37. package/ts-utils.d.ts +2475 -0
  38. package/tsdoc-metadata.json +11 -0
  39. package/utils.d.ts +71 -27
  40. package/utils.d.ts.map +1 -0
  41. package/utils.js +82 -37
  42. package/validation/boolean.d.ts +27 -0
  43. package/validation/boolean.d.ts.map +1 -0
  44. package/validation/boolean.js +59 -0
  45. package/validation/classes.d.ts +5 -0
  46. package/validation/classes.d.ts.map +1 -0
  47. package/validation/classes.js +34 -0
  48. package/validation/field.d.ts +43 -0
  49. package/validation/field.d.ts.map +1 -0
  50. package/validation/field.js +72 -0
  51. package/validation/genericValidator.d.ts +84 -0
  52. package/validation/genericValidator.d.ts.map +1 -0
  53. package/validation/genericValidator.js +138 -0
  54. package/validation/index.d.ts +7 -0
  55. package/validation/index.d.ts.map +1 -0
  56. package/validation/index.js +59 -0
  57. package/validation/number.d.ts +27 -0
  58. package/validation/number.d.ts.map +1 -0
  59. package/validation/number.js +57 -0
  60. package/validation/object.d.ts +115 -0
  61. package/validation/object.d.ts.map +1 -0
  62. package/validation/object.js +143 -0
  63. package/validation/string.d.ts +27 -0
  64. package/validation/string.d.ts.map +1 -0
  65. package/validation/string.js +57 -0
  66. package/validation/traits.d.ts +68 -0
  67. package/validation/traits.d.ts.map +1 -0
  68. package/validation/traits.js +58 -0
  69. package/validation/validator.d.ts +82 -0
  70. package/validation/validator.d.ts.map +1 -0
  71. package/validation/validator.js +24 -0
  72. package/validation/validatorBase.d.ts +25 -0
  73. package/validation/validatorBase.d.ts.map +1 -0
  74. package/validation/validatorBase.js +44 -0
  75. package/validation/validators.d.ts +32 -0
  76. package/validation/validators.d.ts.map +1 -0
  77. package/validation/validators.js +59 -0
package/LICENSE CHANGED
File without changes
package/README.md CHANGED
@@ -21,6 +21,7 @@ Also includes a few other much less-developed odds-and-ends borrowed from one pr
21
21
 
22
22
  - [Summary](#summary)
23
23
  - [Installation](#installation)
24
+ - [API Documentation](#api-documentation)
24
25
  - [Overview](#overview)
25
26
  - [The Result Pattern](#the-result-pattern)
26
27
  - [Converters](#converters)
@@ -40,6 +41,9 @@ With npm:
40
41
  npm install ts-utils
41
42
  ```
42
43
 
44
+ ## API Documentation
45
+ Extracted API documentation is [here](./docs/ts-utils.md).
46
+
43
47
  ## Overview
44
48
  ### The Result Pattern
45
49
 
package/brand.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Helper type to brand a simple type to prevent inappropriate use
3
+ * @public
4
+ */
5
+ export declare type Brand<T, B> = T & {
6
+ __brand: B;
7
+ };
8
+ //# sourceMappingURL=brand.d.ts.map
package/brand.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAEH,oBAAY,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC"}
package/brand.js ADDED
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ /*
3
+ * Copyright (c) 2021 Erik Fortune
4
+ *
5
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ * of this software and associated documentation files (the "Software"), to deal
7
+ * in the Software without restriction, including without limitation the rights
8
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ * copies of the Software, and to permit persons to whom the Software is
10
+ * furnished to do so, subject to the following conditions:
11
+ *
12
+ * The above copyright notice and this permission notice shall be included in all
13
+ * copies or substantial portions of the Software.
14
+ *
15
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ * SOFTWARE.
22
+ */
23
+ Object.defineProperty(exports, "__esModule", { value: true });
24
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnJhbmQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvYnJhbmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW9CRyIsInNvdXJjZXNDb250ZW50IjpbIi8qXG4gKiBDb3B5cmlnaHQgKGMpIDIwMjEgRXJpayBGb3J0dW5lXG4gKlxuICogUGVybWlzc2lvbiBpcyBoZXJlYnkgZ3JhbnRlZCwgZnJlZSBvZiBjaGFyZ2UsIHRvIGFueSBwZXJzb24gb2J0YWluaW5nIGEgY29weVxuICogb2YgdGhpcyBzb2Z0d2FyZSBhbmQgYXNzb2NpYXRlZCBkb2N1bWVudGF0aW9uIGZpbGVzICh0aGUgXCJTb2Z0d2FyZVwiKSwgdG8gZGVhbFxuICogaW4gdGhlIFNvZnR3YXJlIHdpdGhvdXQgcmVzdHJpY3Rpb24sIGluY2x1ZGluZyB3aXRob3V0IGxpbWl0YXRpb24gdGhlIHJpZ2h0c1xuICogdG8gdXNlLCBjb3B5LCBtb2RpZnksIG1lcmdlLCBwdWJsaXNoLCBkaXN0cmlidXRlLCBzdWJsaWNlbnNlLCBhbmQvb3Igc2VsbFxuICogY29waWVzIG9mIHRoZSBTb2Z0d2FyZSwgYW5kIHRvIHBlcm1pdCBwZXJzb25zIHRvIHdob20gdGhlIFNvZnR3YXJlIGlzXG4gKiBmdXJuaXNoZWQgdG8gZG8gc28sIHN1YmplY3QgdG8gdGhlIGZvbGxvd2luZyBjb25kaXRpb25zOlxuICpcbiAqIFRoZSBhYm92ZSBjb3B5cmlnaHQgbm90aWNlIGFuZCB0aGlzIHBlcm1pc3Npb24gbm90aWNlIHNoYWxsIGJlIGluY2x1ZGVkIGluIGFsbFxuICogY29waWVzIG9yIHN1YnN0YW50aWFsIHBvcnRpb25zIG9mIHRoZSBTb2Z0d2FyZS5cbiAqXG4gKiBUSEUgU09GVFdBUkUgSVMgUFJPVklERUQgXCJBUyBJU1wiLCBXSVRIT1VUIFdBUlJBTlRZIE9GIEFOWSBLSU5ELCBFWFBSRVNTIE9SXG4gKiBJTVBMSUVELCBJTkNMVURJTkcgQlVUIE5PVCBMSU1JVEVEIFRPIFRIRSBXQVJSQU5USUVTIE9GIE1FUkNIQU5UQUJJTElUWSxcbiAqIEZJVE5FU1MgRk9SIEEgUEFSVElDVUxBUiBQVVJQT1NFIEFORCBOT05JTkZSSU5HRU1FTlQuIElOIE5PIEVWRU5UIFNIQUxMIFRIRVxuICogQVVUSE9SUyBPUiBDT1BZUklHSFQgSE9MREVSUyBCRSBMSUFCTEUgRk9SIEFOWSBDTEFJTSwgREFNQUdFUyBPUiBPVEhFUlxuICogTElBQklMSVRZLCBXSEVUSEVSIElOIEFOIEFDVElPTiBPRiBDT05UUkFDVCwgVE9SVCBPUiBPVEhFUldJU0UsIEFSSVNJTkcgRlJPTSxcbiAqIE9VVCBPRiBPUiBJTiBDT05ORUNUSU9OIFdJVEggVEhFIFNPRlRXQVJFIE9SIFRIRSBVU0UgT1IgT1RIRVIgREVBTElOR1MgSU4gVEhFXG4gKiBTT0ZUV0FSRS5cbiAqL1xuXG4vKipcbiAqIEhlbHBlciB0eXBlIHRvIGJyYW5kIGEgc2ltcGxlIHR5cGUgdG8gcHJldmVudCBpbmFwcHJvcHJpYXRlIHVzZVxuICogQHB1YmxpY1xuICovXG4vLyBlc2xpbnQtZGlzYWJsZS1uZXh0LWxpbmUgQHR5cGVzY3JpcHQtZXNsaW50L25hbWluZy1jb252ZW50aW9uXG5leHBvcnQgdHlwZSBCcmFuZDxULCBCPiA9IFQgJiB7IF9fYnJhbmQ6IEIgfTtcbiJdfQ==
package/converter.d.ts CHANGED
@@ -1,14 +1,17 @@
1
1
  import { Result } from './result';
2
+ import { Brand } from './brand';
2
3
  declare type OnError = 'failOnError' | 'ignoreErrors';
3
4
  /**
4
5
  * Converter traits.
6
+ * @public
5
7
  */
6
8
  export interface ConverterTraits {
7
9
  readonly isOptional: boolean;
8
10
  readonly brand?: string;
9
11
  }
10
12
  /**
11
- * Options for @see Converter @see withConstraint
13
+ * Options for {@link Converter.withConstraint}.
14
+ * @public
12
15
  */
13
16
  export interface ConstraintOptions {
14
17
  /**
@@ -18,209 +21,250 @@ export interface ConstraintOptions {
18
21
  readonly description: string;
19
22
  }
20
23
  /**
21
- * Helper type to brand a simple type to prevent inappropriate use
24
+ * Generic converter to convert unknown to a templated type `<T>`, using
25
+ * intrinsic rules or as modified by an optional conversion context
26
+ * of optional templated type `<TC>` (default `undefined`).
27
+ * @public
22
28
  */
23
- export declare type Brand<T, B> = T & {
24
- __brand: B;
25
- };
26
29
  export interface Converter<T, TC = undefined> extends ConverterTraits {
27
30
  /**
28
- * Indicates whether this element is explicitly optional
31
+ * Indicates whether this element is explicitly optional.
29
32
  */
30
33
  readonly isOptional: boolean;
31
34
  /**
32
- * Returns the brand for a branded type
35
+ * Returns the brand for a branded type.
33
36
  */
34
37
  readonly brand?: string;
35
38
  /**
36
- * Converts from unknown to <T>
37
- * @param from The unknown to be converted
38
- * @param context An optional context applied to the conversion
39
- * @returns An @see Result with a value or an error message
39
+ * Converts from `unknown` to `<T>`.
40
+ * @param from - The `unknown` to be converted
41
+ * @param context - An optional conversion context of type `<TC>` to be used in
42
+ * the conversion.
43
+ * @returns A {@link Result} with a {@link Success} and a value on success or an
44
+ * {@link Failure} with a a message on failure.
40
45
  */
41
46
  convert(from: unknown, context?: TC): Result<T>;
42
47
  /**
43
- * Converts from unknown to <T> or undefined, as appropriate.
44
- * If 'onError' is 'failOnError', the converter succeeds for
45
- * 'undefined' or any convertible value, but reports an error
46
- * if it encounters a value that cannot be converted. If 'onError'
47
- * is 'ignoreErrors' (default) then values that cannot be converted
48
- * result in a successful return of 'undefined'.
49
- * @param from The unknown to be converted
50
- * @param context Optional context for use by the converter
51
- * @param onError Specifies handling of values that cannot be converted, default 'ignoreErrors'
48
+ * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
49
+ *
50
+ * @remarks
51
+ * If `onError` is `failOnError`, the converter succeeds for
52
+ * `undefined` or any convertible value, but reports an error
53
+ * if it encounters a value that cannot be converted.
54
+ *
55
+ * If `onError` is `ignoreErrors` (default) then values that
56
+ * cannot be converted result in a successful return of `undefined`.
57
+ * @param from - The `unknown` to be converted
58
+ * @param context - An optional conversion context of type `<TC>` to be used in
59
+ * the conversion.
60
+ * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
61
+ * @returns A {@link Result} with a {@link Success} and a value on success or an
62
+ * {@link Failure} with a a message on failure.
52
63
  */
53
64
  convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
54
65
  /**
55
- * Creates a converter for an optional value. If 'onError'
56
- * is 'failOnError', the converter accepts 'undefined' or a
57
- * convertible value, but reports an error if it encounters
58
- * a value that cannot be converted. If 'onError' is 'ignoreErrors'
59
- * (default) then values that cannot be converted result in a
60
- * successful return of 'undefined'.
66
+ * Creates a {@link Converter} for an optional value.
67
+ *
68
+ * @remarks
69
+ * If `onError` is `failOnError`, the resulting converter will accept `undefined`
70
+ * or a convertible value, but report an error if it encounters a value that cannot be
71
+ * converted.
61
72
  *
62
- * @param onError Specifies handling of values that cannot be converted, default 'ignoreErrors'
73
+ * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
74
+ * result in a successful return of `undefined`.
75
+ *
76
+ * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
77
+ * @returns A new {@link Converter} returning `<T|undefined>`.
63
78
  * */
64
79
  optional(onError?: OnError): Converter<T | undefined, TC>;
65
80
  /**
66
- * Applies a (possibly) mapping conversion to the converted value.
67
- * @param mapper A function which maps from the converted type to some other type.
81
+ * Creates a {@link Converter} which applies a (possibly) mapping conversion to
82
+ * the converted value of this {@link Converter}.
83
+ * @param mapper - A function which maps from the the result type `<T>` of this
84
+ * converter to a new result type `<T2>`.
85
+ * @returns A new {@link Converter} returning `<T2>`.
68
86
  */
69
87
  map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;
70
88
  /**
71
- * Applies an additional converter to the converted value.
72
- * @param mapConverter The converter to be applied to the converted value
89
+ * Creates a {@link Converter} which applies an additional supplied
90
+ * converter to the result of this converter.
91
+ *
92
+ * @param mapConverter - The {@link Converter} to be applied to the
93
+ * converted result from this {@link Converter}.
94
+ * @returns A new {@link Converter} returning `<T2>`.
73
95
  */
74
96
  mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
75
97
  /**
76
- * Maps the individual items of the resulting value with the supplied
77
- * map function. Fails if 'from' is not an array.
78
- * @param mapper The map function
98
+ * Creates a {@link Converter} which maps the individual items of a collection
99
+ * resulting from this {@link Converter} using the supplied map fuction.
100
+ *
101
+ * @remarks
102
+ * Fails if `from` is not an array.
103
+ *
104
+ * @param mapper - The map function to be applied to each element of the
105
+ * result of this {@link Converter}.
106
+ * @returns A new {@link Converter} returning `<TI[]>`.
79
107
  */
80
108
  mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
81
109
  /**
82
- * Maps the individual items of the resulting value with the supplied
83
- * converter function. Fails if 'from' is not an array.
84
- * @param mapConverter The map
110
+ * Creates a {@link Converter} which maps the individual items of a collection
111
+ * resulting from this {@link Converter} using the supplied {@link Converter}.
112
+ *
113
+ * @remarks
114
+ * Fails if `from` is not an array.
115
+ *
116
+ * @param mapConverter - The {@link Converter} to be applied to each element of the
117
+ * result of this {@link Converter}.
118
+ * @returns A new {@link Converter} returning `<TI[]>`.
85
119
  */
86
120
  mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
87
121
  /**
88
- * Applies a type guard to the conversion result.
89
- * @param guard The type guard function to apply
90
- * @param message Optional message to be reported on failure
122
+ * Creates a {@link Converter} which applies a supplied type guard to the conversion
123
+ * result.
124
+ * @param guard - The type guard function to apply.
125
+ * @param message - Optional message to be reported if the type guard fails.
126
+ * @returns A new {@link Converter} returning `<TI>`.
91
127
  */
92
128
  withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;
93
129
  /**
94
- * Applies a type guard to each member of the conversion result. Fails
95
- * if the conversion result is not an array or if any member fails the
130
+ * Creates a {@link Converter} which applies a supplied type guard to each member of
131
+ * the conversion result from this converter.
132
+ *
133
+ * @remarks
134
+ * Fails if the conversion result is not an array or if any member fails the
96
135
  * type guard.
97
- * @param guard The type guard function to apply to each element
98
- * @param message Optional message to be reported on failure
136
+ * @param guard - The type guard function to apply to each element.
137
+ * @param message - Optional message to be reported if the type guard fails.
138
+ * @returns A new {@link Converter} returning `<TI>`.
99
139
  */
100
140
  withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;
101
141
  /**
102
- * Creates a converter with an optional constraint. If the base converter
103
- * succeeds, calls a supplied constraint evaluation function with the
104
- * value and fails the conversion if the function returns either false
105
- * or Failure<T>.
142
+ * Creates a {@link Converter} which applies an optional constraint to the result
143
+ * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
144
+ * converter calls a supplied constraint evaluation function with the conversion, which
145
+ * fails the entire conversion if the constraint function returns either `false` or
146
+ * {@link Failure | Failure<T>}.
106
147
  *
107
- * @param constraint Constraint evaluation function
108
- * @param options Options for constraint evaluation
148
+ * @param constraint - Constraint evaluation function.
149
+ * @param options - {@link ConstraintOptions | Options} for constraint evaluation.
150
+ * @returns A new {@link Converter} returning `<T>`.
109
151
  */
110
152
  withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
111
153
  /**
112
- * Adds a brand to the type to prevent mismatched usage of simple types
154
+ * returns a converter which adds a brand to the type to prevent mismatched usage
155
+ * of simple types.
156
+ * @param brand - The brand to be applied to the result value.
157
+ * @returns A {@link Converter} returning `Brand<T, B>`.
113
158
  */
114
159
  withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
115
160
  }
161
+ /**
162
+ * internal
163
+ */
116
164
  declare type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? (TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO) : (TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV);
117
165
  /**
118
166
  * Infers the type that will be returned by an intstantiated converter. Works
119
167
  * for complex as well as simple types.
120
- * @example Infer<typeof Converters.mapOf(Converters.stringArray)> is Map<string, string[]>
168
+ * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
169
+ * @beta
121
170
  */
122
171
  export declare type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;
123
172
  /**
124
173
  * Deprecated name for Infer<T> retained for compatibility
125
174
  * @deprecated use @see Infer instead
175
+ * @internal
126
176
  */
127
177
  export declare type ConvertedToType<TCONV> = Infer<TCONV>;
128
178
  /**
129
- * Simple templated converter wrapper to simplify typed conversion from unknown.
179
+ * Base templated wrapper to simplify creation of new {@link Converter}s.
180
+ * @public
130
181
  */
131
182
  export declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
183
+ /**
184
+ * @internal
185
+ */
132
186
  protected readonly _defaultContext?: TC;
187
+ /**
188
+ * @internal
189
+ */
133
190
  protected _isOptional: boolean;
191
+ /**
192
+ * @internal
193
+ */
134
194
  protected _brand?: string;
135
195
  private readonly _converter;
196
+ /**
197
+ * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.
198
+ * @param converter - The conversion function to be applied.
199
+ * @param defaultContext - Optional conversion context to be used by default.
200
+ * @param traits - Optional {@link ConverterTraits | traits} to be assigned to the resulting
201
+ * converter.
202
+ */
136
203
  constructor(converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>, defaultContext?: TC, traits?: ConverterTraits);
137
204
  /**
138
- * Converts from unknown to <T>
139
- * @param from The unknown to be converted
140
- * @returns An @see Result with a value or an error message
205
+ * {@inheritdoc Converter.isOptional}
141
206
  */
142
- convert(from: unknown, context?: TC): Result<T>;
207
+ get isOptional(): boolean;
143
208
  /**
144
- * Converts from unknown to <T> or undefined, as appropriate.
145
- * If 'onError' is 'failOnError', the converter succeeds for
146
- * 'undefined' or any convertible value, but reports an error
147
- * if it encounters a value that cannot be converted. If 'onError'
148
- * is 'ignoreErrors' (default) then values that cannot be converted
149
- * result in a successful return of 'undefined'.
150
- * @param from The unknown to be converted
151
- * @param onError Specifies handling of values that cannot be converted, default 'ignoreErrors'
209
+ * {@inheritdoc Converter.brand}
152
210
  */
153
- convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
211
+ get brand(): string | undefined;
154
212
  /**
155
- * Creates a converter for an optional value. If 'onError'
156
- * is 'failOnError', the converter accepts 'undefined' or a
157
- * convertible value, but reports an error if it encounters
158
- * a value that cannot be converted. If 'onError' is 'ignoreErrors'
159
- * then values that cannot be converted result in a
160
- * successful return of 'undefined'.
161
- *
162
- * @param onError Specifies handling of values that cannot be converted, default 'ignoreErrors'
163
- * */
164
- optional(onError?: OnError): Converter<T | undefined, TC>;
213
+ * {@inheritdoc Converter.convert}
214
+ */
215
+ convert(from: unknown, context?: TC): Result<T>;
165
216
  /**
166
- * Reports whether this value is explicitly optional
217
+ * {@inheritdoc Converter.convertOptional}
167
218
  */
168
- get isOptional(): boolean;
219
+ convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
169
220
  /**
170
- * Reports the brand of a branded type.
221
+ * {@inheritdoc Converter.optional}
171
222
  */
172
- get brand(): string | undefined;
223
+ optional(onError?: OnError): Converter<T | undefined, TC>;
173
224
  /**
174
- * Applies a (possibly) mapping conversion to the converted value.
175
- * @param mapper A function which maps from the converted type to some other type.
225
+ * {@inheritdoc Converter.map}
176
226
  */
177
227
  map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;
178
228
  /**
179
- * Applies an additional converter to the converted value.
180
- * @param mapConverter The converter to be applied to the converted value
229
+ * {@inheritdoc Converter.mapConvert}
181
230
  */
182
231
  mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
183
232
  /**
184
- * Maps the individual items of the resulting value with the supplied
185
- * map function. Fails if 'from' is not an array.
186
- * @param mapper The map function
233
+ * {@inheritdoc Converter.mapItems}
187
234
  */
188
235
  mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
189
236
  /**
190
- * Maps the individual items of the resulting value with the supplied
191
- * converter function. Fails if 'from' is not an array.
192
- * @param mapConverter The map
237
+ * {@inheritdoc Converter.mapConvertItems}
193
238
  */
194
239
  mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
195
240
  /**
196
- * Applies a type guard to the conversion result.
197
- * @param guard The type guard function to apply
198
- * @param message Optional message to be reported on failure
241
+ * {@inheritdoc Converter.withTypeGuard}
199
242
  */
200
243
  withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;
201
244
  /**
202
- * Applies a type guard to each member of the conversion result. Fails
203
- * if the conversion result is not an array or if any member fails the
204
- * type guard.
205
- * @param guard The type guard function to apply to each element
206
- * @param message Optional message to be reported on failure
245
+ * {@inheritdoc Converter.withItemTypeGuard}
207
246
  */
208
247
  withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;
209
248
  /**
210
- * Creates a converter with an optional constraint. If the base converter
211
- * succeeds, calls a supplied constraint evaluation function with the
212
- * value and fails the conversion if the function returns either false
213
- * or Failure<T>.
214
- *
215
- * @param constraint Constraint evaluation function
249
+ * {@inheritdoc Converter.withConstraint}
216
250
  */
217
251
  withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
218
252
  /**
219
- * Adds a brand to the type to prevent mismatched usage of simple types
253
+ * {@inheritdoc Converter.withBrand}
220
254
  */
221
255
  withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
256
+ /**
257
+ * @internal
258
+ */
222
259
  protected _context(supplied?: TC): TC | undefined;
260
+ /**
261
+ * @internal
262
+ */
223
263
  protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits;
264
+ /**
265
+ * @internal
266
+ */
224
267
  protected _with(traits: Partial<ConverterTraits>): this;
225
268
  }
226
269
  export {};
270
+ //# sourceMappingURL=converter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"converter.d.ts","sourceRoot":"","sources":["../src/converter.ts"],"names":[],"mappings":"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"}