@qezor/structkit 1.0.0 → 1.0.2

package/README.md

@@ -1,9 +1,11 @@
 # @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
 
@@ -21,12 +23,34 @@ npm install @qezor/structkit
 - no callback-style APIs
 - no recursion-heavy deep walkers
 - predictable helpers for arrays, objects, and paths
-- a shared Qezor Bridge contract so other libraries can detect capabilities cleanly
+- 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)`
@@ -38,11 +62,22 @@ npm install @qezor/structkit
 - `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)`
@@ -53,47 +88,64 @@ npm install @qezor/structkit
 - `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 {
-  groupBy,
+  truncate,
+  insertAt,
+  insertText,
+  insertAtPath,
+  findDeep,
+  insertDeep,
   get,
   set,
-  mergeDeep,
-  isEqual,
 } = require("@qezor/structkit")
 
-const users = [
-  { id: "u_1", role: "buyer" },
-  { id: "u_2", role: "buyer" },
-  { id: "u_3", role: "seller" },
-]
-
-const grouped = groupBy(users, "role")
-const state = {}
-
-set(state, "queue.region.city", "Pune")
-
-const region = get(state, "queue.region.city")
-const merged = mergeDeep({}, { demand: { joinedUnits: 12 } }, { demand: { buyers: 3 } })
-const same = isEqual(merged, { demand: { joinedUnits: 12, buyers: 3 } })
+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")
 ```
 
-## Qezor Bridge
-
-The root export carries bridge metadata through `Symbol.for("qezor.bridge")`.
-
-That lets other Qezor libraries detect things like:
-- `structure`
-- `structure:array`
-- `structure:object`
-- `structure:path`
-- `structure:compare`
-
 ## 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

package/index.d.ts

@@ -6,23 +6,93 @@ export type Iteratee<T = unknown, R = unknown> =
   | null
   | undefined
 
-export interface QezorBridge {
-  name: string
-  kind: string
-  version: string
-  capabilities: string[]
-  adapters: string[]
-  dependencies: string[]
+export interface RangeOptions {
+  from?: number
+  start?: number
+  to?: number
+  end?: number
+  count?: number
 }
 
-export const QEZOR_BRIDGE: unique symbol
-export function createQezorBridge(input?: Partial<QezorBridge>): QezorBridge
-export function attachQezorBridge<T extends object>(target: T, input?: Partial<QezorBridge>): T
-export function readQezorBridge(target: unknown): QezorBridge | null
-export function hasQezorCapability(target: unknown, capability: string): boolean
+export interface TextInsertOptions extends RangeOptions {
+  at?: number
+  index?: number
+  before?: string
+  after?: string
+  greedy?: boolean
+  last?: boolean
+}
+
+export interface DeepEntry {
+  value: unknown
+  parent: unknown
+  key: string | null
+  tokens: PathToken[]
+  path: string
+  depth: number
+  pathDepth: number
+  absoluteDepth: number
+  type: string
+  isContainer: boolean
+  isLeaf: boolean
+}
+
+export interface DeepOptions {
+  fromPath?: PathInput
+  scope?: PathInput
+  minDepth?: number
+  maxDepth?: number
+  includeRoot?: boolean
+  includeContainers?: boolean
+  includeLeaves?: boolean
+  order?: "dfs" | "bfs"
+  greedy?: boolean | "last" | "deepest" | "path" | "deepest-path"
+  limit?: number
+  maxNodes?: number
+}
+
+export type DeepPredicate =
+  | ((entry: DeepEntry) => boolean)
+  | string
+  | {
+      path?: string
+      key?: string
+      value?: unknown
+      type?: string
+      depth?: number
+      pathDepth?: number
+      absoluteDepth?: number
+      minDepth?: number
+      maxDepth?: number
+      minPathDepth?: number
+      maxPathDepth?: number
+      includes?: string
+    }
+  | unknown
+
+export function toText(value: unknown): string
+export function sliceText(value: unknown, options?: RangeOptions): string
+export function takeText(value: unknown, count?: number): string
+export function takeRightText(value: unknown, count?: number): string
+export function dropText(value: unknown, count?: number): string
+export function dropRightText(value: unknown, count?: number): string
+export function spliceText(value: unknown, deleteCount?: number, insertion?: unknown, options?: { at?: number; index?: number; from?: number; start?: number }): string
+export function insertText(value: unknown, insertion: unknown, options?: TextInsertOptions): string
+export function replaceRangeText(value: unknown, replacement: unknown, options?: RangeOptions): string
+export function truncate(value: unknown, options?: { maxLength?: number; length?: number; omission?: string; position?: "start" | "middle" | "end" }): string
+export function findSubstring(value: unknown, needle: unknown, options?: RangeOptions & { last?: boolean }): number
+export function countSubstrings(value: unknown, needle: unknown, options?: RangeOptions & { allowOverlap?: boolean }): number
+export function between(value: unknown, left: unknown, right: unknown, options?: RangeOptions & { includeDelimiters?: boolean; greedy?: boolean }): string
+export function splitLines(value: unknown): string[]
+export function splitWords(value: unknown): string[]
 
 export function toArray<T = unknown>(value: unknown): T[]
 export function chunk<T = unknown>(value: unknown, size?: number): T[][]
+export function sliceRange<T = unknown>(value: unknown, options?: RangeOptions): T[]
+export function take<T = unknown>(value: unknown, count?: number): T[]
+export function takeRight<T = unknown>(value: unknown, count?: number): T[]
+export function drop<T = unknown>(value: unknown, count?: number): T[]
+export function dropRight<T = unknown>(value: unknown, count?: number): T[]
 export function compact<T = unknown>(value: unknown): T[]
 export function uniq<T = unknown>(value: unknown): T[]
 export function uniqBy<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>): T[]
@@ -34,12 +104,23 @@ export function countBy<T = unknown>(value: unknown, iteratee?: Iteratee<T, unkn
 export function keyBy<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>): Record<string, T>
 export function sortBy<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>): T[]
 export function flatMap<T = unknown, R = unknown>(value: unknown, iteratee?: Iteratee<T, R | R[]>): R[]
+export function spliceAt<T = unknown>(value: unknown, index: number, deleteCount?: number, items?: T | T[]): T[]
+export function insertAt<T = unknown>(value: unknown, index: number, items: T | T[]): T[]
+export function removeAt<T = unknown>(value: unknown, index: number, count?: number): T[]
+export function replaceRange<T = unknown>(value: unknown, replacement: T | T[], options?: RangeOptions): T[]
+export function move<T = unknown>(value: unknown, fromIndex: number, toIndex: number): T[]
+export function findIndexFrom<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>, options?: RangeOptions): number
+export function findLastIndexFrom<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>, options?: RangeOptions): number
+export function mapRange<T = unknown, R = unknown>(value: unknown, iteratee?: Iteratee<T, R>, options?: RangeOptions): Array<T | R>
+export function filterRange<T = unknown>(value: unknown, iteratee?: Iteratee<T, unknown>, options?: RangeOptions): T[]
 export function sumBy<T = unknown>(value: unknown, iteratee?: Iteratee<T, number>): number
 
 export function tokenizePath(path: PathInput): PathToken[]
 export function get<T = unknown>(value: unknown, path: PathInput, defaultValue?: T): T
 export function has(value: unknown, path: PathInput): boolean
 export function set<T extends object>(target: T, path: PathInput, nextValue: unknown): T
+export function update<T = unknown>(target: T, path: PathInput, updater: (value: unknown, entry: { value: unknown; path: string; tokens: PathToken[] }) => unknown, options?: { defaultValue?: unknown }): T
+export function insertAtPath<T = unknown>(target: T, path: PathInput, insertion: unknown, options?: { at?: number; index?: number; before?: string; after?: string; greedy?: boolean; last?: boolean; key?: string; property?: string; merge?: boolean; createMissing?: boolean; kind?: "array" | "string" | "object" }): T
 export function unset(target: object, path: PathInput): boolean
 export function pick(value: unknown, paths: PathInput | PathInput[]): Record<string, unknown>
 export function omit<T = unknown>(value: T, paths: PathInput | PathInput[]): T
@@ -51,3 +132,10 @@ export function cloneDeep<T = unknown>(value: T): T
 export function mergeDeep<T extends Record<string, unknown>>(target: T, ...sources: Array<Record<string, unknown>>): T
 
 export function isEqual(left: unknown, right: unknown): boolean
+export function iterateDeep(value: unknown, options?: DeepOptions): IterableIterator<DeepEntry>
+export function findDeep(value: unknown, predicate?: DeepPredicate, options?: DeepOptions): DeepEntry | undefined
+export function filterDeep(value: unknown, predicate?: DeepPredicate, options?: DeepOptions): DeepEntry[]
+export function findPaths(value: unknown, predicate?: DeepPredicate, options?: DeepOptions): string[]
+export function mapDeep<T = unknown>(value: T, predicate: DeepPredicate, updater: (value: unknown, entry: DeepEntry) => unknown, options?: DeepOptions): T
+export function removeDeep<T = unknown>(value: T, predicate: DeepPredicate, options?: DeepOptions): T | undefined
+export function insertDeep<T = unknown>(value: T, predicate: DeepPredicate, insertion: unknown | ((value: unknown, entry: DeepEntry) => unknown), options?: DeepOptions & { at?: number; index?: number; before?: string; after?: string; greedy?: boolean | "last" | "deepest" | "path" | "deepest-path"; last?: boolean; key?: string; property?: string; merge?: boolean; createMissing?: boolean; kind?: "array" | "string" | "object" }): T

package/index.js

@@ -1,30 +1,15 @@
 "use strict"
 
-const bridge = require("./lib/bridge.js")
+const string = require("./lib/string.js")
 const array = require("./lib/array.js")
 const object = require("./lib/object.js")
 const compare = require("./lib/compare.js")
+const deep = require("./lib/deep.js")
 
-module.exports = bridge.attachQezorBridge({
+module.exports = {
+  ...string,
   ...array,
   ...object,
   ...compare,
-  QEZOR_BRIDGE: bridge.QEZOR_BRIDGE,
-  createQezorBridge: bridge.createQezorBridge,
-  attachQezorBridge: bridge.attachQezorBridge,
-  readQezorBridge: bridge.readQezorBridge,
-  hasQezorCapability: bridge.hasQezorCapability,
-}, {
-  name: "@qezor/structkit",
-  kind: "library",
-  version: "1.0.0",
-  capabilities: [
-    "bridge",
-    "structure",
-    "structure:array",
-    "structure:object",
-    "structure:path",
-    "structure:compare",
-  ],
-  adapters: ["plain-data"],
-})
+  ...deep,
+}

package/index.mjs

@@ -1,8 +1,28 @@
 import mod from "./index.js"
 
 export const {
+  toText,
+  sliceText,
+  takeText,
+  takeRightText,
+  dropText,
+  dropRightText,
+  spliceText,
+  insertText,
+  replaceRangeText,
+  truncate,
+  findSubstring,
+  countSubstrings,
+  between,
+  splitLines,
+  splitWords,
   toArray,
   chunk,
+  sliceRange,
+  take,
+  takeRight,
+  drop,
+  dropRight,
   compact,
   uniq,
   uniqBy,
@@ -14,11 +34,22 @@ export const {
   keyBy,
   sortBy,
   flatMap,
+  spliceAt,
+  insertAt,
+  removeAt,
+  replaceRange,
+  move,
+  findIndexFrom,
+  findLastIndexFrom,
+  mapRange,
+  filterRange,
   sumBy,
   tokenizePath,
   get,
   has,
   set,
+  update,
+  insertAtPath,
   unset,
   pick,
   omit,
@@ -29,11 +60,13 @@ export const {
   cloneDeep,
   mergeDeep,
   isEqual,
-  QEZOR_BRIDGE,
-  createQezorBridge,
-  attachQezorBridge,
-  readQezorBridge,
-  hasQezorCapability,
+  iterateDeep,
+  findDeep,
+  filterDeep,
+  findPaths,
+  mapDeep,
+  removeDeep,
+  insertDeep,
 } = mod
 
 export default mod

package/lib/array.js

@@ -1,6 +1,7 @@
 "use strict"
 
 const { createIteratee } = require("./shared.js")
+const { normalizeRange, normalizeInsertIndex, normalizeCount } = require("./range.js")
 
 function toArray(value) {
   if (value == null) return []
@@ -21,6 +22,35 @@ function chunk(value, size = 1) {
   return output
 }
 
+function sliceRange(value, options = {}) {
+  const list = toArray(value)
+  const range = normalizeRange(list.length, options)
+  return list.slice(range.start, range.end)
+}
+
+function take(value, count = 1) {
+  return sliceRange(value, {
+    start: 0,
+    count: normalizeCount(count, 1),
+  })
+}
+
+function takeRight(value, count = 1) {
+  const list = toArray(value)
+  const amount = normalizeCount(count, 1)
+  return list.slice(Math.max(0, list.length - amount))
+}
+
+function drop(value, count = 1) {
+  const list = toArray(value)
+  return list.slice(Math.min(list.length, normalizeCount(count, 1)))
+}
+
+function dropRight(value, count = 1) {
+  const list = toArray(value)
+  return list.slice(0, Math.max(0, list.length - normalizeCount(count, 1)))
+}
+
 function compact(value) {
   return toArray(value).filter(Boolean)
 }
@@ -157,6 +187,101 @@ function flatMap(value, iteratee) {
   return output
 }
 
+function spliceAt(value, index, deleteCount = 0, items = []) {
+  const list = toArray(value)
+  const at = normalizeInsertIndex(list.length, index, list.length)
+  const removeCount = normalizeCount(deleteCount, 0)
+  const insertItems = Array.isArray(items)
+    ? items.slice()
+    : items === undefined
+      ? []
+      : [items]
+  return [
+    ...list.slice(0, at),
+    ...insertItems,
+    ...list.slice(Math.min(list.length, at + removeCount)),
+  ]
+}
+
+function insertAt(value, index, items) {
+  return spliceAt(value, index, 0, items)
+}
+
+function removeAt(value, index, count = 1) {
+  return spliceAt(value, index, count, [])
+}
+
+function replaceRange(value, replacement, options = {}) {
+  const list = toArray(value)
+  const range = normalizeRange(list.length, options)
+  return spliceAt(list, range.start, range.length, replacement)
+}
+
+function move(value, fromIndex, toIndex) {
+  const list = toArray(value)
+  if (!list.length) return list
+
+  const from = normalizeInsertIndex(list.length, fromIndex, 0)
+  const to = normalizeInsertIndex(list.length, toIndex, list.length - 1)
+  if (from === to) return list
+
+  const item = list[from]
+  const without = removeAt(list, from, 1)
+  const adjustedTo = from < to ? to - 1 : to
+  return insertAt(without, adjustedTo, item)
+}
+
+function findIndexFrom(value, iteratee, options = {}) {
+  const list = toArray(value)
+  const resolve = createIteratee(iteratee)
+  const range = normalizeRange(list.length, options)
+
+  for (let index = range.start; index < range.end; index += 1) {
+    if (resolve(list[index], index, list)) return index
+  }
+
+  return -1
+}
+
+function findLastIndexFrom(value, iteratee, options = {}) {
+  const list = toArray(value)
+  const resolve = createIteratee(iteratee)
+  const range = normalizeRange(list.length, options)
+
+  for (let index = range.end - 1; index >= range.start; index -= 1) {
+    if (resolve(list[index], index, list)) return index
+  }
+
+  return -1
+}
+
+function mapRange(value, iteratee, options = {}) {
+  const list = toArray(value)
+  const resolve = createIteratee(iteratee)
+  const range = normalizeRange(list.length, options)
+  const output = list.slice()
+
+  for (let index = range.start; index < range.end; index += 1) {
+    output[index] = resolve(list[index], index, list)
+  }
+
+  return output
+}
+
+function filterRange(value, iteratee, options = {}) {
+  const list = toArray(value)
+  const resolve = createIteratee(iteratee)
+  const range = normalizeRange(list.length, options)
+  const output = []
+
+  for (let index = range.start; index < range.end; index += 1) {
+    const item = list[index]
+    if (resolve(item, index, list)) output.push(item)
+  }
+
+  return output
+}
+
 function sumBy(value, iteratee) {
   const list = toArray(value)
   const resolve = createIteratee(iteratee)
@@ -173,6 +298,11 @@ function sumBy(value, iteratee) {
 module.exports = {
   toArray,
   chunk,
+  sliceRange,
+  take,
+  takeRight,
+  drop,
+  dropRight,
   compact,
   uniq,
   uniqBy,
@@ -184,5 +314,14 @@ module.exports = {
   keyBy,
   sortBy,
   flatMap,
+  spliceAt,
+  insertAt,
+  removeAt,
+  replaceRange,
+  move,
+  findIndexFrom,
+  findLastIndexFrom,
+  mapRange,
+  filterRange,
   sumBy,
 }