json-mason
v1.0.0
Published
A library for performing structured modifications on JSON data. It provides a safe, predictable way to transform JSON objects through a series of operations.
Downloads
19
Maintainers
Readme
json-mason
Json Mason is a library for performing structured modifications on JSON data. It provides a safe, predictable way to transform JSON objects through a series of operations.
It is light-weight, dependency-free, type-safe yet feature-full.
Features
- 🛠️ Structured JSON modifications
- 🎯 Path-based targeting
- ⚡ Array and string manipulations
- 🔄 Deep cloning of data
- 🐛 Comprehensive error handling
- 🔒 Type-safe operations
Installation
npm install json-mason
# or
yarn add json-mason
pnpm add json-mason
bun add json-mason
Quick Start
import { JsonMason } from 'json-mason';
const mason = new JsonMason();
const data = {
user: {
name: "John",
tags: ["user"]
}
};
const operations = [
{ path: ["user", "name"], action: "set", value: "John Smith" },
{ path: ["user", "tags"], action: "append", value: "admin" }
];
const result = mason.apply(data, operations);
// Result:
// {
// user: {
// name: "John Smith",
// tags: ["user", "admin"]
// }
// }
API Reference
JsonMason Class
apply<T>(source: T, operations: Operation[], config?: Config): T
Applies a series of operations to a source object.
const mason = new JsonMason();
// Single operation
const result1 = mason.apply(data, [
{ path: ["user", "name"], action: "set", value: "John" }
]);
// Multiple operations
const result2 = mason.apply(data, [
{ path: ["users"], action: "set", value: [] },
{ path: ["users"], action: "append", value: { id: 1 }}
]);
// With config
const result3 = mason.apply(data, operations, { strict: false });
getErrors(): OperationError[]
Retrieves errors from the last operation (when strict mode is disabled).
const mason = new JsonMason();
mason.apply(data, operations, { strict: false });
const errors = mason.getErrors();
// [{index: 0, operation: {...}, reason: "..."}]
Supported Operations
Set Operation
Sets a value at a specific path.
const operation = {
path: ["user", "settings", "theme"],
action: "set",
value: "dark"
};
Append Operation
Appends a value to an array or string.
// Array append
const arrayOp = {
path: ["tags"],
action: "append",
value: "new-tag"
};
// String append
const stringOp = {
path: ["message"],
action: "append",
value: " World"
};
Prepend Operation
Prepends a value to an array or string.
// Array prepend
const arrayOp = {
path: ["tags"],
action: "prepend",
value: "important"
};
// String prepend
const stringOp = {
path: ["message"],
action: "prepend",
value: "Hello "
};
Delete Operation
Removes a value at a specific path.
const operation = {
path: ["user", "temporary"],
action: "delete"
};
Configuration
You can configure JsonMason behavior using the Config object:
interface Config {
strict?: boolean; // When true, throws errors immediately. Default: true
}
Example:
// Throw immediately on error (default)
const result = mason.apply(data, operations, { strict: true });
// Continue on errors
const result = mason.apply(data, operations, { strict: false });
Error Handling
JsonMason provides detailed error information when operations fail:
try {
mason.apply(data, operations);
} catch (error) {
console.error(error.message);
}
// Or in non-strict mode:
mason.apply(data, operations, { strict: false });
const errors = mason.getErrors();
errors.forEach(error => {
console.log(`Operation ${error.index} failed: ${error.reason}`);
});
Type Safety
JsonMason is written in TypeScript and provides full type safety:
import { Operation } from 'json-mason';
// Type-checked operations
const operation: Operation = {
path: ["users", 0, "name"],
action: "set",
value: "John"
};
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.