map-obj

map-obj

Version 6.0.0
Published 17 days ago
16.5 kB
No dependencies
MIT license

Install

npm i map-obj

yarn add map-obj

pnpm add map-obj

Overview

Map object keys and values into a new object

Index

Variables

variable mapObjectSkip

const mapObjectSkip: Symbol;

Return this value from a mapper function to remove a key from an object.

Example 1

import mapObject, {mapObjectSkip} from 'map-obj';

const object = {one: 1, two: 2};
const mapper = (key, value) => value === 1 ? [key, value] : mapObjectSkip;
const result = mapObject(object, mapper);

console.log(result);
//=> {one: 1}

Functions

function mapObject

mapObject: {
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        TargetObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: DeepMapperWithSymbols<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: DeepOptions & SymbolOptions & TargetOptions<TargetObjectType>
    ): TargetObjectType & Record<string | symbol, unknown>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: DeepMapperWithSymbols<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: { readonly deep: true } & Options & {
                readonly includeSymbols: true;
            }
    ): Record<string | symbol, unknown>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        TargetObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: MapperWithSymbols<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: { readonly includeSymbols: true } & Options & {
                readonly target: TargetObjectType;
            }
    ): TargetObjectType & Record<MappedObjectKeyType, MappedObjectValueType>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: MapperWithSymbols<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: SymbolOptions
    ): Record<MappedObjectKeyType, MappedObjectValueType>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        TargetObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: DeepMapper<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: { readonly deep: true } & Options & {
                readonly target: TargetObjectType;
            }
    ): TargetObjectType & Record<string | symbol, unknown>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: DeepMapper<
            SourceObjectType,
            MappedObjectKeyType,
            MappedObjectValueType
        >,
        options: DeepOptions
    ): Record<string | symbol, unknown>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        TargetObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: Mapper<SourceObjectType, MappedObjectKeyType, MappedObjectValueType>,
        options: TargetOptions<TargetObjectType>
    ): TargetObjectType & Record<MappedObjectKeyType, MappedObjectValueType>;
    <
        SourceObjectType extends Record<string | symbol, unknown>,
        MappedObjectKeyType extends string | symbol,
        MappedObjectValueType
    >(
        source: SourceObjectType,
        mapper: Mapper<SourceObjectType, MappedObjectKeyType, MappedObjectValueType>,
        options?: Options
    ): Record<MappedObjectKeyType, MappedObjectValueType>;
};

Map object keys and values into a new object.

Parameter source

The source object to copy properties from.

Parameter mapper

A mapping function.

Example 1

import mapObject, {mapObjectSkip} from 'map-obj';

// Swap keys and values
const newObject = mapObject({foo: 'bar'}, (key, value) => [value, key]);
//=> {bar: 'foo'}

// Convert keys to lowercase (shallow)
const newObject = mapObject({FOO: true, bAr: {bAz: true}}, (key, value) => [key.toLowerCase(), value]);
//=> {foo: true, bar: {bAz: true}}

// Convert keys to lowercase (deep recursion)
const newObject = mapObject({FOO: true, bAr: {bAz: true}}, (key, value) => [key.toLowerCase(), value], {deep: true});
//=> {foo: true, bar: {baz: true}}

// Filter out specific values
const newObject = mapObject({one: 1, two: 2}, (key, value) => value === 1 ? [key, value] : mapObjectSkip);
//=> {one: 1}

// Include symbol keys
const symbol = Symbol('foo');
const newObject = mapObject({bar: 'baz', [symbol]: 'qux'}, (key, value) => [key, value], {includeSymbols: true});
//=> {bar: 'baz', [Symbol(foo)]: 'qux'}

Type Aliases

type DeepMapper

type DeepMapper<
    SourceObjectType extends Record<string | symbol, unknown>,
    MappedObjectKeyType extends string | symbol,
    MappedObjectValueType
> = (
    sourceKey: string,
    sourceValue: unknown,
    source: SourceObjectType
) =>
    | [
          targetKey: MappedObjectKeyType,
          targetValue: MappedObjectValueType,
          mapperOptions?: MapperOptions
      ]
    | typeof mapObjectSkip;

Mapper used when {deep: true} is enabled.
In deep mode we may visit nested objects with keys and values unrelated to the top-level object, so we intentionally widen the key and value types.

type DeepMapperWithSymbols

type DeepMapperWithSymbols<
    SourceObjectType extends Record<string | symbol, unknown>,
    MappedObjectKeyType extends string | symbol,
    MappedObjectValueType
> = (
    sourceKey: string | symbol,
    sourceValue: unknown,
    source: SourceObjectType
) =>
    | [
          targetKey: MappedObjectKeyType,
          targetValue: MappedObjectValueType,
          mapperOptions?: MapperOptions
      ]
    | typeof mapObjectSkip;

Deep mapper when includeSymbols: true is enabled.

type DeepOptions

type DeepOptions = {
    readonly deep: true;
} & Options;

type Mapper

type Mapper<
    SourceObjectType extends Record<string | symbol, unknown>,
    MappedObjectKeyType extends string | symbol,
    MappedObjectValueType
> = (
    sourceKey: Extract<keyof SourceObjectType, string>,
    sourceValue: SourceObjectType[keyof SourceObjectType],
    source: SourceObjectType
) =>
    | [
          targetKey: MappedObjectKeyType,
          targetValue: MappedObjectValueType,
          mapperOptions?: MapperOptions
      ]
    | typeof mapObjectSkip;

Mapper function for transforming object keys and values.

type MapperOptions

type MapperOptions = {
    /**
	Whether to recurse into `targetValue`.

	Requires `deep: true`.

	@default true
	*/
    readonly shouldRecurse?: boolean;
};

type MapperWithSymbols

type MapperWithSymbols<
    SourceObjectType extends Record<string | symbol, unknown>,
    MappedObjectKeyType extends string | symbol,
    MappedObjectValueType
> = (
    sourceKey: keyof SourceObjectType,
    sourceValue: SourceObjectType[keyof SourceObjectType],
    source: SourceObjectType
) =>
    | [
          targetKey: MappedObjectKeyType,
          targetValue: MappedObjectValueType,
          mapperOptions?: MapperOptions
      ]
    | typeof mapObjectSkip;

Mapper function when includeSymbols: true is enabled.

type Options

type Options = {
    /**
	Recurse nested objects and objects in arrays.

	@default false

	Built-in objects like `RegExp`, `Error`, `Date`, `Map`, `Set`, `WeakMap`, `WeakSet`, `Promise`, `ArrayBuffer`, `DataView`, typed arrays (Uint8Array, etc.), and `Blob` are not recursed into. Special objects like Jest matchers are also automatically excluded.
	*/
    readonly deep?: boolean;

    /**
	Include symbol keys in the iteration.

	By default, symbol keys are completely ignored and not passed to the mapper function. When enabled, the mapper will also be called with symbol keys from the source object, allowing them to be transformed or included in the result. Only enumerable symbol properties are included.

	@default false
	*/
    readonly includeSymbols?: boolean;

    /**
	The target object to map properties onto.

	@default {}
	*/
    readonly target?: Record<string | symbol, unknown>;
};

type SymbolOptions

type SymbolOptions = {
    readonly includeSymbols: true;
} & Options;

type TargetOptions

type TargetOptions<TargetObjectType extends Record<string | symbol, unknown>> = {
    readonly target: TargetObjectType;
} & Options;

Package Files (1)

index.d.ts

Dependencies (0)

No dependencies.

Dev Dependencies (3)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/map-obj.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/map-obj)

HTML

<a href="https://www.jsdocs.io/package/map-obj"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 13 days ago.
Package analyzed in 1592 ms.
Missing or incorrect documentation? Open an issue for this package.