assert-json-object
Version:
🧪 Fluent, chainable assertions for JSON structures with dot-path access.
219 lines (156 loc) • 7.96 kB
Markdown
# assert-json-object
🧪 Fluent, chainable assertions for JSON structures with dot-path access.
[](LICENSE)
## ✨ Features
- Assert deeply nested JSON properties using dot-paths (e.g. `"foo.bar[0].baz"`)
- Type and value assertions
- Predicate-based assertions
- Negation (`not`) support
- **Soft assertion** mode: collect all errors instead of throwing immediately
- TypeScript support
- 🪶 Zero dependencies
---
## 📦 Install
```bash
npm install assert-json-object
```
## 🚀 Usage
```typescript
import { assertJson } from "assert-json-object";
const data = {
user: {
name: "Alice",
age: 30,
tags: ["admin", "editor"],
address: { city: "NYC" },
},
};
const assertion = assertJson(data);
assertion
.toHaveKey("user.name")
.toBeType("user.age", "number")
.toMatchValue("user.address.city", "NYC")
.not.toHaveKey("user.password");
// No error thrown
```
### Soft Assertion Mode
Collect all assertion errors and inspect them later:
```typescript
const assertion = assertJson(data, { soft: true });
assertion
.toHaveKey("user.name")
.toBeType("user.age", "string") // error
.toMatchValue("user.address.city", "LA") // error
.not.toHaveKey("user.name"); // error
console.log(assertion.getErrors());
```
---
## ⚙️ API
### `assertJson(data, options?)`
- `data`: The JSON object to assert on.
- `options.soft` (optional): If `true`, enables soft assertion mode.
Returns a `JsonAssertion` instance.
### Assertion Methods
| Method | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `.toHaveKey(path)` | Asserts that the given dot-path exists. |
| `.toBeType(path, type)` | Asserts the value at path is of the given type (`string`, `number`, `boolean`, `object`, `array`, `undefined`, `null`). |
| `.toMatchValue(path, expected)` | Asserts the value at path equals the expected value (deep equality). |
| `.toSatisfy(path, predicate)` | Asserts the value at path satisfies the predicate function. |
| `.not` | Negates the next assertion. |
| `.getErrors()` | Returns an array of errors (only in soft mode). |
---
## ✅ Examples
### Basic
```typescript
assertJson({ foo: 1 }).toHaveKey("foo").toBeType("foo", "number");
// No error thrown
```
### Negation
```typescript
assertJson({ foo: 1 }).not.toHaveKey("bar");
// No error thrown
assertJson({ foo: 1 }).not.toHaveKey("foo");
// Throws: Error: Expected key 'foo' not to exist
```
### Array Indexing
```typescript
const data = { arr: [{ id: 1 }, { id: 2 }] };
assertJson(data).toHaveKey("arr[1].id").toMatchValue("arr[0].id", 1);
// No error thrown
assertJson(data).toHaveKey("arr[2].id");
// Throws: Error: Expected key 'arr[2].id' to exist
```
### Soft Assertion
```typescript
const assertion = assertJson({ foo: 1 }, { soft: true });
assertion.toHaveKey("foo").toBeType("foo", "string"); // error
console.log(assertion.getErrors().length);
// Output: 1
console.log(assertion.getErrors()[0].message);
// Output: Expected 'foo' to be type 'string', but got 'number'
```
---
## 🧩 More Examples
### Type and Value Checks
```typescript
const data = { a: 123, b: "hello", c: null, d: [1, 2], e: { x: 1 } };
assertJson(data)
.toBeType("a", "number")
.toBeType("b", "string")
.toBeNull("c")
.toBeType("d", "array")
.toBeType("e", "object")
.toBeDefined("a")
.toBeTruthy("b")
.toBeFalsy("c");
```
### Array and String Containment
```typescript
const data = { arr: [1, 2, 3], str: "hello world" };
assertJson(data).toContainValue("arr", 2).toContainValue("str", "world").not.toContainValue("arr", 5);
```
### Numeric Comparisons
```typescript
const data = { score: 42 };
assertJson(data)
.toBeGreaterThan("score", 10)
.toBeLessThan("score", 100)
.not.toBeGreaterThan("score", 100)
.not.toBeLessThan("score", 10);
```
### One Of / Enum
```typescript
const data = { status: "pending" };
assertJson(data).toBeOneOf("status", ["pending", "done", "failed"]).not.toBeOneOf("status", ["archived"]);
```
### Custom Predicate
```typescript
const data = { value: 15 };
assertJson(data)
.toSatisfy("value", (v) => typeof v === "number" && v % 5 === 0)
.not.toSatisfy("value", (v) => v < 0);
```
---
## 🔎 More Matchers
| Method | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `.toHaveKey(path)` | Asserts that the given dot-path exists. |
| `.not.toHaveKey(path)` | Asserts that the given dot-path does NOT exist. |
| `.toBeType(path, type)` | Asserts the value at path is of the given type (`string`, `number`, `boolean`, `object`, `array`, `undefined`, `null`). |
| `.toBeDefined(path)` | Asserts the value at path is defined (not `undefined`). |
| `.toBeNull(path)` | Asserts the value at path is `null`. |
| `.toBeTruthy(path)` | Asserts the value at path is truthy. |
| `.toBeFalsy(path)` | Asserts the value at path is falsy. |
| `.toMatchValue(path, expected)` | Asserts the value at path equals the expected value (deep equality). |
| `.toContainValue(path, value)` | Asserts the value at path (array or string) contains the given value. |
| `.toBeGreaterThan(path, number)` | Asserts the value at path is a number greater than the given number. |
| `.toBeLessThan(path, number)` | Asserts the value at path is a number less than the given number. |
| `.toBeOneOf(path, [values])` | Asserts the value at path matches any value in the provided array (deep equality). |
| `.toSatisfy(path, predicate)` | Asserts the value at path satisfies the predicate function. |
| `.not` | Negates the next assertion. |
| `.getErrors()` | Returns an array of errors (only in soft mode). |
---
## 📄 License
MIT © jaktestowac.pl
Powered by [jaktestowac.pl](https://www.jaktestowac.pl/) team!