Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aralroca/default-composer

A tiny (~500B) JavaScript library that allows you to set default values for nested objects
https://github.com/aralroca/default-composer

composer defaults javascript json merge mix nested-objects tree typescript

Last synced: 5 days ago
JSON representation

A tiny (~500B) JavaScript library that allows you to set default values for nested objects

Host: GitHub
URL: https://github.com/aralroca/default-composer
Owner: aralroca
License: mit
Created: 2023-05-26T15:56:47.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2023-11-22T16:07:22.000Z (about 1 year ago)
Last Synced: 2024-12-06T05:32:03.279Z (7 days ago)
Topics: composer, defaults, javascript, json, merge, mix, nested-objects, tree, typescript
Language: TypeScript
Homepage:
Size: 142 KB
Stars: 468
Watchers: 7
Forks: 12
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

my-awesome-list - default-composer

README

        






Default composer





_A **tiny** (~500B) **JavaScript library** that allows you to set **default values** for **nested objects**_

[![npm version](https://badge.fury.io/js/default-composer.svg)](https://badge.fury.io/js/default-composer)

[![gzip size](https://img.badgesize.io/https://unpkg.com/default-composer?compression=gzip&label=gzip)](https://unpkg.com/default-composer)

[![CI Status](https://github.com/aralroca/default-composer/actions/workflows/test.yml/badge.svg)](https://github.com/aralroca/default-composer/actions/workflows/test.yml)

[![Maintenance Status](https://badgen.net/badge/maintenance/active/green)](https://github.com/aralroca/default-composer#maintenance-status)

[![Weekly downloads](https://badgen.net/npm/dw/default-composer?color=blue)](https://www.npmjs.com/package/default-composer)

[![PRs Welcome][badge-prwelcome]][prwelcome]

[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)

[badge-prwelcome]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square

[prwelcome]: http://makeapullrequest.com

"default-composer" is a JavaScript library that allows you to set default values for **nested objects**. The library replaces empty strings/arrays/objects, null, or undefined values in an existing object with the defined default values, which helps simplify programming logic and reduce the amount of code needed to set default values.

**Content**:

- [1. Installation](#installation)

- [2. Usage](#usage)

- [3. API](#api)

  - [`defaultComposer`](#defaultcomposer)

  - [`setConfig`](#setconfig)

    - [`isDefaultableValue`](#isdefaultablevalue)

    - [`mergeArrays`](#mergearrays)

- [4. TypeScript](#typescript)

- [5. Contributing](#contributing)

- [6. License](#license)

- [7. Credits](#credits)

- [8. Contributors](#contributors-)

## Installation

You can install "default-composer" using npm:

```bh

npm install default-composer

```

or with yarn:

```bh

yarn add default-composer

```

## Usage

To use "default-composer", simply import the library and call the `defaultComposer()` function with the default values object and the original object that you want to set default values for. For example:

```js

import { defaultComposer } from "default-composer";

const defaults = {

  name: "Aral 😊",

  surname: "",

  isDeveloper: true,

  isDesigner: false,

  age: 33,

  address: {

    street: "123 Main St",

    city: "Anytown",

    state: "CA",

  },

  emails: ["[email protected]"],

  hobbies: ["programming"],

};

const originalObject = {

  name: "Aral",

  emails: [],

  phone: "555555555",

  age: null,

  address: {

    zip: "54321",

  },

  hobbies: ["parkour", "computer science", "books", "nature"],

};

const result = defaultComposer(defaults, originalObject);

console.log(result);

```

This will output:

```js

{

  name: 'Aral',

  surname: '',

  isDeveloper: true,

  isDesigner: false,

  emails: ['[email protected]'],

  phone: '555555555',

  age: 33,

  address: {

    street: '123 Main St',

    city: 'Anytown',

    state: 'CA',

    zip: '54321'

  },

  hobbies: ['parkour', 'computer science', 'books', 'nature'],

}

```

## API

### `defaultComposer`

```js

defaultComposer(defaultsPriorityN, [..., defaultsPriority2, defaultsPriority1, objectWithData])

```

This function takes one or more objects as arguments and returns a new object with default values applied. The first argument should be an object containing the default values to apply. Subsequent arguments should be the objects to apply the default values to.

If a property in a given object is either empty, null, or undefined, and the corresponding property in the defaults object is not empty, null, or undefined, the default value will be used.

**Example**:

```js

import { defaultComposer } from "default-composer";

const defaultsPriority1 = {

  name: "Aral 😊",

  hobbies: ["reading"],

};

const defaultsPriority2 = {

  name: "Aral 🤔",

  age: 33,

  address: {

    street: "123 Main St",

    city: "Anytown",

    state: "CA",

    zip: "12345",

  },

  hobbies: ["reading", "hiking"],

};

const object = {

  address: {

    street: "",

    city: "Anothercity",

    state: "NY",

    zip: "",

  },

  hobbies: ["running"],

};

const result = defaultComposer(defaultsPriority2, defaultsPriority1, object);

console.log(result);

```

This will output:

```js

{

  name: 'Aral 😊',

  age: 33,

  address: {

    street: '123 Main St',

    city: 'Anothercity',

    state: 'NY',

    zip: '12345'

  },

  hobbies: ['running']

}

```

### `setConfig`

`setConfig` is a function that allows you to set configuration options for `defaultComposer`.

This is the available configuration:

- **`isDefaultableValue`**, is a function that determines whether a value should be considered defaultable or not.

- **`mergeArrays`**, is a boolean to define if you want to merge arrays (`true`) or not (`false`), when is set to `false` is just replacing to the default value when the original array is empty. By default is `false`.

#### `isDefaultableValue`

You can use `setConfig` to provide your own implementation of `isDefaultableValue` if you need to customize this behavior.

```ts

type IsDefaultableValueParams = ({

  key,

  value,

  defaultableValue,

}: {

  key: string;

  value: unknown;

  defaultableValue: boolean; // In case you want to re-use the default behavior

}) => boolean;

```

The `defaultableValue` boolean is the result of the default behavior of `isDefaultableValue`. By default, is detected as `defaultableValue` when is `null`, `undefined`, an empty `string`, an empty `array`, or an empty `object`.

Here is an example of how you can use `setConfig`:

```ts

import { defaultComposer, setConfig } from "default-composer";

const isNullOrWhitespace = ({ key, value }) => {

  return value === null || (typeof value === "string" && value.trim() === "");

};

setConfig({ isDefaultableValue: isNullOrWhitespace });

const defaults = { example: "replaced", anotherExample: "also replaced" };

const originalObject = { example: "   ", anotherExample: null };

const result = defaultComposer(defaults, originalObject);

console.log(result); // { example: 'replaced', anotherExample: 'also replaced' }

```

Here is another example of how you can use `setConfig` reusing the `defaultableValue`:

```ts

import { defaultComposer, setConfig } from "default-composer";

setConfig({

  isDefaultableValue({ key, value, defaultableValue }) {

    return (

      defaultableValue || (typeof value === "string" && value.trim() === "")

    );

  },

});

const defaults = { example: "replaced", anotherExample: "also replaced" };

const originalObject = { example: "   ", anotherExample: null };

const result = defaultComposer(defaults, originalObject);

console.log(result); // { example: 'replaced', anotherExample: 'also replaced' }

```

#### `mergeArrays`

Example to merge arrays:

```ts

const defaults = {

  hobbies: ["reading"],

};

const object = {

  hobbies: ["running"],

};

setConfig({ mergeArrays: true});

defaultComposer(defaults, object)) // { hobbies: ["reading", "running"]}

```

## TypeScript

In order to use in TypeScript you can pass a generic with the expected output, and all the expected input by default should be partials of this generic.

Example:

```ts

type Addres = {

  street: string;

  city: string;

  state: string;

  zip: string;

};

type User = {

  name: string;

  age: number;

  address: Address;

  hobbies: string[];

};

const defaults = {

  name: "Aral 😊",

  hobbies: ["reading"],

};

const object = {

  age: 33,

  address: {

    street: "",

    city: "Anothercity",

    state: "NY",

    zip: "",

  },

  hobbies: [],

};

defaultComposer(defaults, object);

```

## Contributing

Contributions to "default-composer" are welcome! If you find a bug or want to suggest a new feature, please open an issue on the GitHub repository. If you want to contribute code, please fork the repository and submit a pull request with your changes.

## License

"default-composer" is licensed under the MIT license. See [LICENSE](LICENSE) for more information.

## Credits

"default-composer" was created by [Aral Roca](https://github.com/aralroca).



## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    

      
_{Aral Roca Gomez}
💻 🚧

      
_{Robin Pokorny}
💻

      
_{Muslim Idris}
💻

      
_namhtpyn
🚇

      
_{Josu Martinez}
🐛

    

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!