flatohh

flatohh

The "Fletó" of flattening utilities. A lightweight TypeScript utility for deeply flattening, unflattening, filtering, pruning, and restructuring nested JavaScript objects and arrays.

Why?

Transform deeply nested objects into flat, dot-notation key-value pairs (and back again). Perfect for:

• 🔍 Searching through complex nested structures
• 📝 Working with form data and dot-notation paths
• 🗄️ Storing hierarchical data in flat databases
• 🔄 Converting between different data formats
• ⚡ Deep Filtering & Chaining
• ✂️ Deep Pruning (Modifying Inner Arrays)
• 🛠️ Structural Renaming (Hoisting/Nesting)
• 🪄 Deep Transformation & Selection (Pick/Omit)

📦 Universal Compatibility

flatohh is built to work everywhere out of the box.

• ✅ CommonJS (CJS): Fully supported for Node.js (legacy & modern).
• ✅ ES Modules (ESM/MJS): Native support for modern stack (Vite, Next.js, etc.).
• ✅ TypeScript: First-class citizen. Includes native .d.ts type definitions.
• ✅ Legacy Support: Compiles down to ES5, compatible with Node.js 7+.

Quick Start

npm install flatohh

import { flatten, deflatten, flatChain, rename, flatTransform, flatPick, flatOmit } from 'flatohh';

// 1. The Classic Flatten
const ferenc = { name: "Ferenc", attributes: { nickname: "Fletó" } };
const flat = flatten(ferenc);
// { "name": "Ferenc", "attributes.nickname": "Fletó" }

// 2. The New Power Features (Renaming & Filtering)
const data = [
  { id: 1, meta: { active: true, role: 'admin', sensitive: 'secret' } },
  { id: 2, meta: { active: false, role: 'user', sensitive: 'hidden' } }
];

const admins = flatChain(data)
  .filter({ 'meta.active': true })
  .value();

// 3. Transformation & Selection
// Apply 10% tax, pick specific fields, and remove sensitive data
const taxed = flatTransform(data, { 'meta.price': (p) => p * 1.1 });
const picked = flatPick(taxed, ['id', 'meta.*']);
const safe = flatOmit(picked, ['meta.sensitive']);

Features

✨ Simple API - flatten, deflatten, rename, flatFilter, flatModify, flatChain, flatTransform, flatPick, flatOmit

🔒 Type-safe - Full TypeScript support

📦 Flexible Input - Accepts objects or JSON strings

🎯 Smart Notation - Dot notation for objects, bracket notation for arrays

⚡ Zero Dependencies - Lightweight and fast

✂️ Deep Pruning - Modify inner arrays using wildcard houses[*] syntax

🛠️ Structure Shifting - Move data deeper or pull it up using rename

🔍 Deep Query Engine - MongoDB-style logic ($and, $or, $not, $elemMatch) for arrays

Installation

npm install flatohh

yarn add flatohh

Usage

Importing

ES Modules / TypeScript

import { flatten, deflatten, flatTransform, flatPick, flatOmit } from 'flatohh';

CommonJS (Node.js)

const { flatten, deflatten, flatTransform, flatPick, flatOmit } = require('flatohh');

1. Flatten

Convert nested structures to flat key-value pairs.

Basic Example

const data = {
  user: {
    name: 'John',
    age: 30,
    settings: {
      theme: 'dark',
      notifications: true
    }
  }
};

const flat = flatten(data);
// {
//   'user.name': 'John',
//   'user.age': 30,
//   'user.settings.theme': 'dark',
//   'user.settings.notifications': true
// }

With Arrays

const data = {
  users: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
};

const flat = flatten(data);
// {
//   'users[0].id': 1,
//   'users[0].name': 'Alice',
//   'users[1].id': 2,
//   'users[1].name': 'Bob'
// }

With Custom Prefix

const data = { name: 'Alice', age: 25 };
const flat = flatten(data, 'user');
// {
//   'user.name': 'Alice',
//   'user.age': 25
// }

From JSON String

const jsonStr = '{"name":"Alice","address":{"city":"NYC"}}';
const flat = flatten(jsonStr);
// Automatically parses and flattens

2. Deflatten

Reconstruct nested objects from flat structures.

Basic Example

const flat = {
  'name': 'Alice',
  'address.city': 'NYC',
  'address.zip': '10001'
};

const nested = deflatten(flat);
// {
//   name: 'Alice',
//   address: { city: 'NYC', zip: '10001' }
// }

Reconstructing Arrays

const flat = {
  'items[0].name': 'Apple',
  'items[1].name': 'Orange'
};

const nested = deflatten(flat);
// {
//   items: [
//     { name: 'Apple' },
//     { name: 'Orange' }
//   ]
// }

Direct to JSON

const flat = { 'name': 'Alice', 'age': 25 };
const jsonStr = deflatten.toJson(flat);
// '{"name":"Alice","age":25}'

3. Rename (Restructuring)

Structurally transform objects by moving properties to new paths.

const data = {
  userId: 123,
  config: { theme: 'dark' }
};

const result = rename(data, {
  // Push 'userId' deeper into a 'meta' object
  'userId': 'meta.id',
  
  // Rename 'config' object to 'settings' (moves all children automatically)
  'config': 'settings'
});

// Result:
// {
//   meta: { id: 123 },
//   settings: { theme: 'dark' }
// }

4. Filter Arrays (flatFilter)

Filter arrays of nested objects without flattening them first.

Basic & Logical Filtering

const users = [
  { id: 1, meta: { active: true, role: 'admin' } },
  { id: 2, meta: { active: false, role: 'user' } }
];

// Keep users where active is true AND role is admin
const admins = flatFilter(users, {
  'meta.active': true,
  'meta.role': 'admin'
});

// Logical Operators
const result = flatFilter(users, {
  $or: [
    { 'meta.role': 'admin' },
    { 'meta.role': 'guest' }
  ]
});

Deep Array Tunneling

Automatically check deeply nested arrays (e.g., Parent -> Children -> Toys).

// Find parents who have ANY child with a broken toy
flatFilter(parents, {
  'children.toys.status': 'broken'
});

Checking for Existence (undefined)

Check if a nested key is missing or undefined.

// Find users missing a profile
const incomplete = flatFilter(users, {
  'user.profile': undefined
});

// Find users who HAVE a profile (Not Undefined)
const complete = flatFilter(users, {
  $not: { 'user.profile': undefined }
});

Advanced: Correlated Sub-queries ($elemMatch)

By default, checks are "Global" (Does the parent have any red house and any rotten apple?). Use $elemMatch to enforce that multiple conditions must be met by the same sub-object.

// Delete the village ONLY if it has a house that is BOTH Yellow AND has Rotten Apples
const safeVillages = flatFilter(villages, {
  $not: {
    'houses': {
      $elemMatch: {
        'color': 'yellow',
        'boxes.apples.status': 'rotten'
      }
    }
  }
});

5. Deep Pruning (flatModify)

Modify inner arrays without writing nested loops. Use the [*] wildcard to target an array for filtering.

Pruning Child Arrays

Remove items from a child array based on deep logic.

const villages = [
  { name: 'Village A', houses: [{ id: 1, bad: false }, { id: 2, bad: true }] }
];

// Keep the village, but remove the bad houses inside it
const cleanVillages = flatModify(villages, {
  'houses[*]': {
    $not: { 'bad': true }
  }
});
// Result: Village A remains, but now has only House 1.

Recursive Pruning

Go deeper! Modify the grandchildren.

// Don't delete the house. Just delete the rotten box INSIDE the house.
const result = flatModify(villages, {
  'houses[*].boxes[*]': {
    $not: { 'apples.status': 'rotten' }
  }
});

6. Piping (flatChain)

Chain multiple filtering steps together efficiently. Uses Lazy Execution to optimize into a single pass.

const result = flatChain(data)
  // Step 1: Filter by deep property
  .filter({ 'attributes.color': 'red' })
  
  // Step 2: Filter by logic
  .filter({ 
    $or: [
      { status: 'active' },
      { status: 'pending' }
    ]
  })
  .value();

7. Deep Transformation (flatTransform)

Modify values at specific deep paths (including within arrays) using mapper functions.

const products = [
  { id: 1, info: { price: 100, name: 'Apple' } },
  { id: 2, info: { price: 200, name: 'Banana' } }
];

// Apply 10% tax to all prices across nested structures
const taxed = flatTransform(products, {
  'info.price': (p) => p * 1.1
});
// Result: Prices are now 110 and 220

Transforming Nested Arrays

Use the [*] wildcard to apply transformations to every item in a nested list.

flatTransform(orders, {
  'items[*].qty': (q) => q * 2 // Double the quantity of all items
});

8. Selection (flatPick / flatOmit)

Surgical property selection using dot-notation. This is safer than standard picking because it understands nested structures and arrays.

const user = {
  id: 1,
  profile: { name: 'Alice', age: 30, internalId: 'SECRET' },
  tags: ['admin', 'verified']
};

// Pick only what you need (Whitelist)
const publicUser = flatPick(user, ['id', 'profile.name', 'tags[*]']);
// -> { id: 1, profile: { name: 'Alice' }, tags: [...] }

// Omit sensitive fields (Blacklist)
const safeUser = flatOmit(user, ['profile.internalId', 'profile.age']);
// -> { id: 1, profile: { name: 'Alice' }, ... }

API Reference

flatten(obj, prefix?, result?)

Converts a nested object into a flat structure.

Parameter	Type	Default	Description
obj	`object	string`	required
prefix	string	''	Optional prefix for all keys
result	object	{}	Existing object to mutate (advanced)

Returns: Record<string, any> - Flat object with dot/bracket notation keys

deflatten(flatObj)

Reconstructs a nested object from a flat structure.

Parameter	Type	Description
flatObj	`object	string`

Returns: Record<string, any> - Nested object structure

rename(obj, mapping)

Structurally transforms the object.

Parameter	Type	Description
obj	object	The source object
mapping	Record<string, string>	Map of { oldPath: newPath }

Returns: object - The restructured object.

Note: This acts as a "Move" operation. If moving a property leaves its parent object empty, the parent is automatically removed from the result.

flatFilter(array, query)

Filters an array of objects using deep dot-notation paths and logical operators.

Parameter	Type	Description
array	Array<any>	The array of objects to filter
query	object	The filter criteria with dot-paths or $and/$or/$not/$elemMatch

Returns: Array<any> - A new array containing only items that match the query.

flatModify(array, rules)

Modifies deeply nested arrays in place (returned as new copy).

Parameter	Type	Description
array	Array<any>	The root array
rules	Record<string, Query>	Map of path[*] -> FilterQuery

Returns: Array<any> - The modified structure.

flatChain(array)

Creates a fluent chain for piping operations.

Method	Description
.filter(query)	Adds a deep filter step to the pipe.
.value()	Executes the optimized pipe and returns the result.

flatTransform(data, mapping)

Transforms values at specific paths.

Parameter	Type	Description
data	`object	Array`
mapping	Record<string, Function>	Map of path -> MapperFunction(value) => newValue

Returns: object | Array - The transformed data (structure preserved).

flatPick(obj, paths)

Returns a new object containing only the specified paths.

Parameter	Type	Description
obj	object	Source object
paths	string[]	Array of dot-notation paths to keep. Supports [*]

flatOmit(obj, paths)

Returns a new object excluding the specified paths.

Parameter	Type	Description
obj	object	Source object
paths	string[]	Array of dot-notation paths to remove. Supports [*]

License

MIT © [Imre Toth]