npm package: @qezor/structkit
Description: Iterative string, array, object, and deep-structure manipulation utilities with precise range and depth controls.
Author: Abdul Ahad
Latest version: 1.0.2

# @qezor/structkit

`@qezor/structkit` is a focused data-manipulation toolkit for:
- strings
- arrays
- objects
- path access
- iterative deep traversal and filtering
- iterative deep equality
- iterative deep merge and clone

It is built to cover the high-use utility surface people often reach for in lodash, without turning into a bag of random helpers.

## Install

```bash
npm install @qezor/structkit
```

## What It Prioritizes

- iterative internals for deep operations
- no callback-style APIs
- no recursion-heavy deep walkers
- predictable helpers for arrays, objects, and paths
- range-controlled string and array operations
- depth-controlled deep search and deep manipulation
- generator-based traversal so large structures do not need to be fully materialized

## Main Helpers

- `toText(value)`
- `sliceText(value, options)`
- `takeText(value, count)`
- `takeRightText(value, count)`
- `dropText(value, count)`
- `dropRightText(value, count)`
- `spliceText(value, deleteCount, insertion, options)`
- `insertText(value, insertion, options)`
- `replaceRangeText(value, replacement, options)`
- `truncate(value, options)`
- `findSubstring(value, needle, options)`
- `countSubstrings(value, needle, options)`
- `between(value, left, right, options)`
- `splitLines(value)`
- `splitWords(value)`
- `toArray(value)`
- `chunk(array, size)`
- `sliceRange(array, options)`
- `take(array, count)`
- `takeRight(array, count)`
- `drop(array, count)`
- `dropRight(array, count)`
- `compact(array)`
- `uniq(array)`
- `uniqBy(array, iteratee)`
- `difference(array, values)`
- `intersection(array, values)`
- `partition(array, iteratee)`
- `groupBy(array, iteratee)`
- `countBy(array, iteratee)`
- `keyBy(array, iteratee)`
- `sortBy(array, iteratee)`
- `flatMap(array, iteratee)`
- `spliceAt(array, index, deleteCount, items)`
- `insertAt(array, index, items)`
- `removeAt(array, index, count)`
- `replaceRange(array, replacement, options)`
- `move(array, fromIndex, toIndex)`
- `findIndexFrom(array, iteratee, options)`
- `findLastIndexFrom(array, iteratee, options)`
- `mapRange(array, iteratee, options)`
- `filterRange(array, iteratee, options)`
- `sumBy(array, iteratee)`
- `tokenizePath(path)`
- `get(value, path, defaultValue)`
- `has(value, path)`
- `set(value, path, nextValue)`
- `update(value, path, updater, options)`
- `insertAtPath(value, path, insertion, options)`
- `unset(value, path)`
- `pick(value, paths)`
- `omit(value, paths)`
- `mapValues(object, iteratee)`
- `defaults(target, ...sources)`
- `assignDefined(target, ...sources)`
- `cloneShallow(value)`
- `cloneDeep(value)`
- `mergeDeep(target, ...sources)`
- `isEqual(left, right)`
- `iterateDeep(value, options)`
- `findDeep(value, predicate, options)`
- `filterDeep(value, predicate, options)`
- `findPaths(value, predicate, options)`
- `mapDeep(value, predicate, updater, options)`
- `removeDeep(value, predicate, options)`
- `insertDeep(value, predicate, insertion, options)`

## Usage

```js
const {
  truncate,
  insertAt,
  insertText,
  insertAtPath,
  findDeep,
  insertDeep,
  get,
  set,
} = require("@qezor/structkit")

const queue = {
  region: { city: "Pune" },
  buyers: [{ id: "u_1" }, { id: "u_2" }],
}

set(queue, "limits.moq", 500)

const title = truncate("Wholesale demand aggregation for notebooks", {
  maxLength: 24,
})

const buyers = insertAt(queue.buyers, 1, { id: "u_1_5" })
const label = insertText("bulkbuy", "-", { after: "bulk" })
insertAtPath(queue, "buyers", { id: "u_0" }, { index: 0 })
const cityNode = findDeep(queue, { path: "region.city" })
const upgraded = insertDeep(
  { regions: [["Pune"], ["Mumbai"]] },
  { path: "regions[1]" },
  "Nagpur",
  { index: 1 }
)

const city = get(queue, "region.city")
```

## Notes

- string and array range operations use inclusive start and exclusive end semantics under the hood
- `between(..., { greedy: true })` uses the farthest right delimiter inside the active range
- `insertText()` can place content by index or relative to `before` / `after` markers, with optional greedy matching
- `spliceAt()` is the low-level array primitive behind insert/remove/replace behavior
- `update()` is the clean path-based updater when `get()` + `set()` would be noisy
- `insertAtPath()` and `insertDeep()` cover precise insertion without hand-writing clone/update boilerplate
- deep traversal is iterative and generator-based, so large structures can be walked progressively
- in deep helpers, `depth` means structural depth from `fromPath`, while `pathDepth` tracks raw path length from `fromPath`
- use `fromPath`, `minDepth`, `maxDepth`, `minPathDepth`, `maxPathDepth`, `greedy`, `limit`, and `maxNodes` to stay precise and resource-safe
- deep clone, deep merge, and deep equality use iterative walkers instead of recursion
- arrays are replaced during `mergeDeep()` instead of element-wise merged
- `omit()` works on cloned data, so the original input is left untouched
- `set()` mutates the provided target, like many performance-oriented utility helpers do