default-composer v0.6.0
A tiny (~500B) JavaScript library that allows you to set default values for nested objects
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:
Installation
You can install "default-composer" using npm:
npm install default-composer
or with yarn:
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:
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: ["contact@aralroca.com"],
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:
{
name: 'Aral',
surname: '',
isDeveloper: true,
isDesigner: false,
emails: ['contact@aralroca.com'],
phone: '555555555',
age: 33,
address: {
street: '123 Main St',
city: 'Anytown',
state: 'CA',
zip: '54321'
},
hobbies: ['parkour', 'computer science', 'books', 'nature'],
}
API
defaultComposer
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:
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:
{
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 tofalse
is just replacing to the default value when the original array is empty. By default isfalse
.
isDefaultableValue
You can use setConfig
to provide your own implementation of isDefaultableValue
if you need to customize this behavior.
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
:
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<any>(defaults, originalObject);
console.log(result); // { example: 'replaced', anotherExample: 'also replaced' }
Here is another example of how you can use setConfig
reusing the defaultableValue
:
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<any>(defaults, originalObject);
console.log(result); // { example: 'replaced', anotherExample: 'also replaced' }
mergeArrays
Example to merge arrays:
const defaults = {
hobbies: ["reading"],
};
const object = {
hobbies: ["running"],
};
setConfig({ mergeArrays: true});
defaultComposer<any>(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:
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<User>(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 for more information.
Credits
"default-composer" was created by Aral Roca.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!