UNPKG

3.58 kBTypeScriptView Raw
1/**
2Return this value from a `mapper` function to remove a key from an object.
3
4@example
5```
6import mapObject, {mapObjectSkip} from 'map-obj';
7
8const object = {one: 1, two: 2}
9const mapper = (key, value) => value === 1 ? [key, value] : mapObjectSkip
10const result = mapObject(object, mapper);
11
12console.log(result);
13//=> {one: 1}
14```
15*/
16export const mapObjectSkip: unique symbol;
17
18export type Mapper<
19 SourceObjectType extends Record<string, any>,
20 MappedObjectKeyType extends string,
21 MappedObjectValueType,
22> = (
23 sourceKey: keyof SourceObjectType,
24 sourceValue: SourceObjectType[keyof SourceObjectType],
25 source: SourceObjectType
26) => [
27 targetKey: MappedObjectKeyType,
28 targetValue: MappedObjectValueType,
29 mapperOptions?: MapperOptions,
30] | typeof mapObjectSkip;
31
32export interface Options {
33 /**
34 Recurse nested objects and objects in arrays.
35
36 @default false
37 */
38 readonly deep?: boolean;
39
40 /**
41 The target object to map properties on to.
42
43 @default {}
44 */
45 readonly target?: Record<string, any>;
46}
47
48export interface DeepOptions extends Options {
49 readonly deep: true;
50}
51
52export interface TargetOptions<TargetObjectType extends Record<string, any>> extends Options {
53 readonly target: TargetObjectType;
54}
55
56export interface MapperOptions {
57 /**
58 Whether `targetValue` should be recursed.
59
60 Requires `deep: true`.
61
62 @default true
63 */
64 readonly shouldRecurse?: boolean;
65}
66
67/**
68Map object keys and values into a new object.
69
70@param source - The source object to copy properties from.
71@param mapper - A mapping function.
72
73@example
74```
75import mapObject, {mapObjectSkip} from 'map-obj';
76
77const newObject = mapObject({foo: 'bar'}, (key, value) => [value, key]);
78//=> {bar: 'foo'}
79
80const newObject = mapObject({FOO: true, bAr: {bAz: true}}, (key, value) => [key.toLowerCase(), value]);
81//=> {foo: true, bar: {bAz: true}}
82
83const newObject = mapObject({FOO: true, bAr: {bAz: true}}, (key, value) => [key.toLowerCase(), value], {deep: true});
84//=> {foo: true, bar: {baz: true}}
85
86const newObject = mapObject({one: 1, two: 2}, (key, value) => value === 1 ? [key, value] : mapObjectSkip);
87//=> {one: 1}
88```
89*/
90export default function mapObject<
91 SourceObjectType extends Record<string, unknown>,
92 TargetObjectType extends Record<string, any>,
93 MappedObjectKeyType extends string,
94 MappedObjectValueType,
95>(
96 source: SourceObjectType,
97 mapper: Mapper<
98 SourceObjectType,
99 MappedObjectKeyType,
100 MappedObjectValueType
101 >,
102 options: DeepOptions & TargetOptions<TargetObjectType>
103): TargetObjectType & Record<string, unknown>;
104export default function mapObject<
105 SourceObjectType extends Record<string, unknown>,
106 MappedObjectKeyType extends string,
107 MappedObjectValueType,
108>(
109 source: SourceObjectType,
110 mapper: Mapper<
111 SourceObjectType,
112 MappedObjectKeyType,
113 MappedObjectValueType
114 >,
115 options: DeepOptions
116): Record<string, unknown>;
117export default function mapObject<
118 SourceObjectType extends Record<string, any>,
119 TargetObjectType extends Record<string, any>,
120 MappedObjectKeyType extends string,
121 MappedObjectValueType,
122>(
123 source: SourceObjectType,
124 mapper: Mapper<
125 SourceObjectType,
126 MappedObjectKeyType,
127 MappedObjectValueType
128 >,
129 options: TargetOptions<TargetObjectType>
130): TargetObjectType & {[K in MappedObjectKeyType]: MappedObjectValueType};
131export default function mapObject<
132 SourceObjectType extends Record<string, any>,
133 MappedObjectKeyType extends string,
134 MappedObjectValueType,
135>(
136 source: SourceObjectType,
137 mapper: Mapper<
138 SourceObjectType,
139 MappedObjectKeyType,
140 MappedObjectValueType
141 >,
142 options?: Options
143): {[K in MappedObjectKeyType]: MappedObjectValueType};