@qezor/structkit 1.0.1 → 1.0.2

package/lib/string.js

@@ -0,0 +1,195 @@
+"use strict"
+
+const { normalizeRange, normalizeCount, clampIndex } = require("./range.js")
+
+function toText(value) {
+  if (value == null) return ""
+  return String(value)
+}
+
+function sliceText(value, options = {}) {
+  const text = toText(value)
+  const range = normalizeRange(text.length, options)
+  return text.slice(range.start, range.end)
+}
+
+function takeText(value, count = 1) {
+  return sliceText(value, {
+    start: 0,
+    count: normalizeCount(count, 1),
+  })
+}
+
+function takeRightText(value, count = 1) {
+  const text = toText(value)
+  const amount = normalizeCount(count, 1)
+  return text.slice(Math.max(0, text.length - amount))
+}
+
+function dropText(value, count = 1) {
+  const text = toText(value)
+  return text.slice(Math.min(text.length, normalizeCount(count, 1)))
+}
+
+function dropRightText(value, count = 1) {
+  const text = toText(value)
+  return text.slice(0, Math.max(0, text.length - normalizeCount(count, 1)))
+}
+
+function spliceText(value, deleteCount = 0, insertion = "", options = {}) {
+  const text = toText(value)
+  const removeCount = normalizeCount(deleteCount, 0)
+  const next = insertion == null ? "" : String(insertion)
+  const at = clampIndex(text.length, options.at ?? options.index ?? options.from ?? options.start, text.length)
+  return `${text.slice(0, at)}${next}${text.slice(Math.min(text.length, at + removeCount))}`
+}
+
+function resolveTextMatchIndex(text, needle, range, greedy) {
+  if (!needle) return range.start
+  if (greedy) {
+    const index = text.lastIndexOf(needle, Math.max(range.start, range.end - needle.length))
+    return index >= range.start && index < range.end ? index : -1
+  }
+  const index = text.indexOf(needle, range.start)
+  return index >= range.start && index < range.end ? index : -1
+}
+
+function insertText(value, insertion, options = {}) {
+  const text = toText(value)
+  const range = normalizeRange(text.length, options)
+  let at
+
+  if (options.before != null || options.after != null) {
+    const needle = String(options.before ?? options.after)
+    const matchIndex = resolveTextMatchIndex(text, needle, range, options.greedy === true || options.last === true)
+    if (matchIndex === -1) return text
+    at = options.before != null ? matchIndex : matchIndex + needle.length
+  } else {
+    at = clampIndex(text.length, options.at ?? options.index ?? options.from ?? options.start, text.length)
+  }
+
+  return spliceText(text, 0, insertion, { at })
+}
+
+function replaceRangeText(value, replacement, options = {}) {
+  const text = toText(value)
+  const range = normalizeRange(text.length, options)
+  return spliceText(text, range.length, replacement, { at: range.start })
+}
+
+function truncate(value, options = {}) {
+  const text = toText(value)
+  const maxLength = normalizeCount(options.maxLength ?? options.length, text.length)
+  const omission = options.omission == null ? "..." : String(options.omission)
+  const position = options.position || "end"
+
+  if (text.length <= maxLength) return text
+  if (maxLength <= omission.length) return omission.slice(0, maxLength)
+
+  const remaining = maxLength - omission.length
+
+  if (position === "start") {
+    return `${omission}${text.slice(text.length - remaining)}`
+  }
+
+  if (position === "middle") {
+    const left = Math.ceil(remaining / 2)
+    const right = Math.floor(remaining / 2)
+    return `${text.slice(0, left)}${omission}${text.slice(text.length - right)}`
+  }
+
+  return `${text.slice(0, remaining)}${omission}`
+}
+
+function findSubstring(value, needle, options = {}) {
+  const text = toText(value)
+  const search = String(needle == null ? "" : needle)
+  const range = normalizeRange(text.length, options)
+
+  if (!search) return range.start
+
+  if (options.last === true) {
+    const index = text.lastIndexOf(search, Math.max(range.start, range.end - search.length))
+    return index >= range.start && index < range.end ? index : -1
+  }
+
+  const index = text.indexOf(search, range.start)
+  return index >= range.start && index < range.end ? index : -1
+}
+
+function countSubstrings(value, needle, options = {}) {
+  const text = toText(value)
+  const search = String(needle == null ? "" : needle)
+  const range = normalizeRange(text.length, options)
+  const allowOverlap = options.allowOverlap === true
+
+  if (!search) return 0
+
+  let count = 0
+  let cursor = range.start
+
+  while (cursor < range.end) {
+    const index = text.indexOf(search, cursor)
+    if (index === -1 || index >= range.end) break
+    count += 1
+    cursor = index + (allowOverlap ? 1 : search.length)
+  }
+
+  return count
+}
+
+function between(value, left, right, options = {}) {
+  const text = toText(value)
+  const startNeedle = String(left == null ? "" : left)
+  const endNeedle = String(right == null ? "" : right)
+  const range = normalizeRange(text.length, options)
+
+  const leftIndex = startNeedle
+    ? text.indexOf(startNeedle, range.start)
+    : range.start
+
+  if (leftIndex === -1 || leftIndex >= range.end) return ""
+
+  const start = startNeedle ? leftIndex + startNeedle.length : leftIndex
+  const rightIndex = endNeedle
+    ? options.greedy === true
+      ? text.lastIndexOf(endNeedle, Math.max(start, range.end - endNeedle.length))
+      : text.indexOf(endNeedle, start)
+    : range.end
+
+  if (rightIndex === -1 || rightIndex > range.end || rightIndex < start) return ""
+  if (options.includeDelimiters) {
+    return text.slice(startNeedle ? leftIndex : start, endNeedle ? rightIndex + endNeedle.length : rightIndex)
+  }
+  return text.slice(start, rightIndex)
+}
+
+function splitLines(value) {
+  const text = toText(value)
+  if (!text) return []
+  return text.split(/\r\n|\n|\r/)
+}
+
+function splitWords(value) {
+  const text = toText(value).trim()
+  if (!text) return []
+  return text.split(/\s+/u)
+}
+
+module.exports = {
+  toText,
+  sliceText,
+  takeText,
+  takeRightText,
+  dropText,
+  dropRightText,
+  spliceText,
+  insertText,
+  replaceRangeText,
+  truncate,
+  findSubstring,
+  countSubstrings,
+  between,
+  splitLines,
+  splitWords,
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qezor/structkit",
-  "version": "1.0.1",
-  "description": "Iterative array and object utilities for high-use data shaping without callback hell or recursion-heavy internals.",
+  "version": "1.0.2",
+  "description": "Iterative string, array, object, and deep-structure manipulation utilities with precise range and depth controls.",
   "files": [
     "LICENSE",
     "README.md",
@@ -29,7 +29,9 @@
   },
   "keywords": [
     "array",
+    "string",
     "object",
+    "deep",
     "utility",
     "lodash",
     "iterative",

package/test.js

@@ -4,7 +4,21 @@ const test = require("node:test")
 const assert = require("node:assert/strict")
 const structkit = require("./index.js")
 
-test("array helpers cover grouping uniqueness and sums", () => {
+test("string helpers support range-limited manipulation and searching", () => {
+  assert.equal(structkit.sliceText("wholesale-pricing", { start: 0, end: 9 }), "wholesale")
+  assert.equal(structkit.takeRightText("pricing", 4), "cing")
+  assert.equal(structkit.spliceText("bulkbuy", 0, "-", { at: 4 }), "bulk-buy")
+  assert.equal(structkit.insertText("bulkbuy", "-", { after: "bulk" }), "bulk-buy")
+  assert.equal(structkit.replaceRangeText("groupbuy", "pool", { start: 0, end: 5 }), "poolbuy")
+  assert.equal(structkit.truncate("The power of bulk buying", { maxLength: 14 }), "The power o...")
+  assert.equal(structkit.findSubstring("stationary notebooks", "note"), 11)
+  assert.equal(structkit.countSubstrings("aaaa", "aa", { allowOverlap: true }), 3)
+  assert.equal(structkit.between("Qezor [CADAAD] queue", "[", "]"), "CADAAD")
+  assert.equal(structkit.between("a[b]c[d]e", "[", "]", { greedy: true }), "b]c[d")
+  assert.deepEqual(structkit.splitWords("bulk buying for all"), ["bulk", "buying", "for", "all"])
+})
+
+test("array helpers cover grouping, ranges, and ordered manipulation", () => {
   const buyers = [
     { id: "u1", role: "buyer", qty: 2 },
     { id: "u2", role: "buyer", qty: 5 },
@@ -13,9 +27,21 @@ test("array helpers cover grouping uniqueness and sums", () => {
   ]
 
   assert.deepEqual(structkit.chunk([1, 2, 3, 4, 5], 2), [[1, 2], [3, 4], [5]])
+  assert.deepEqual(structkit.sliceRange([1, 2, 3, 4, 5], { start: 1, end: 4 }), [2, 3, 4])
+  assert.deepEqual(structkit.take([1, 2, 3], 2), [1, 2])
+  assert.deepEqual(structkit.dropRight([1, 2, 3, 4], 2), [1, 2])
   assert.deepEqual(structkit.compact([0, 1, false, 2, "", 3]), [1, 2, 3])
   assert.deepEqual(structkit.uniq([1, 1, 2, 3, 3]), [1, 2, 3])
   assert.deepEqual(structkit.uniqBy(buyers, "id").map((item) => item.id), ["u1", "u2", "u3"])
+  assert.deepEqual(structkit.spliceAt([1, 2, 5], 2, 0, [3, 4]), [1, 2, 3, 4, 5])
+  assert.deepEqual(structkit.insertAt([1, 3], 1, 2), [1, 2, 3])
+  assert.deepEqual(structkit.removeAt([1, 2, 3, 4], 1, 2), [1, 4])
+  assert.deepEqual(structkit.replaceRange([1, 2, 3, 4], [8, 9], { start: 1, end: 3 }), [1, 8, 9, 4])
+  assert.deepEqual(structkit.move(["a", "b", "c", "d"], 1, 3), ["a", "c", "b", "d"])
+  assert.equal(structkit.findIndexFrom([5, 7, 9, 12], (value) => value > 8, { start: 1 }), 2)
+  assert.equal(structkit.findLastIndexFrom([5, 7, 9, 12], (value) => value > 6, { end: 3 }), 2)
+  assert.deepEqual(structkit.mapRange([1, 2, 3, 4], (value) => value * 10, { start: 1, end: 3 }), [1, 20, 30, 4])
+  assert.deepEqual(structkit.filterRange([1, 2, 3, 4, 5], (value) => value % 2 === 0, { start: 1, end: 4 }), [2, 4])
   assert.deepEqual(structkit.groupBy(buyers, "role"), {
     buyer: [buyers[0], buyers[1]],
     seller: [buyers[2], buyers[3]],
@@ -33,13 +59,20 @@ test("path and object helpers work iteratively", () => {
   structkit.set(state, "queue.regions[0].city", "Pune")
   structkit.set(state, "queue.regions[0].active", true)
   structkit.set(state, ["queue", "meta", "moq"], 500)
+  structkit.set(state, "queue.label", "GroupBuy")
+  structkit.update(state, "queue.meta.moq", (value) => value + 100)
+  structkit.insertAtPath(state, "queue.regions", { city: "Mumbai" }, { index: 1 })
+  structkit.insertAtPath(state, "queue.label", " ", { before: "Buy" })
 
   assert.equal(structkit.get(state, "queue.regions[0].city"), "Pune")
+  assert.equal(structkit.get(state, "queue.regions[1].city"), "Mumbai")
+  assert.equal(structkit.get(state, "queue.label"), "Group Buy")
+  assert.equal(structkit.get(state, "queue.meta.moq"), 600)
   assert.equal(structkit.has(state, "queue.meta.moq"), true)
   assert.deepEqual(structkit.tokenizePath("queue.regions[0].city"), ["queue", "regions", 0, "city"])
   assert.deepEqual(structkit.pick(state, ["queue.meta.moq", "queue.regions[0].city"]), {
     queue: {
-      meta: { moq: 500 },
+      meta: { moq: 600 },
       regions: [{ city: "Pune" }],
     },
   })
@@ -93,3 +126,84 @@ test("mapValues and defaults keep object helpers practical", () => {
     { a: 1, b: 6 }
   )
 })
+
+test("deep helpers support precise search and manipulation without recursion", () => {
+  const value = {
+    queue: {
+      regions: [
+        { city: "Pune", meta: { active: true } },
+        { city: "Mumbai", meta: { active: false } },
+      ],
+      stats: { joined: 12 },
+    },
+  }
+
+  const entries = [...structkit.iterateDeep(value, {
+    fromPath: "queue",
+    maxDepth: 2,
+    includeContainers: false,
+  })]
+  assert.equal(entries.some((entry) => entry.path === "queue.regions[0].city"), true)
+  assert.equal(entries.some((entry) => entry.path === "queue.regions[0].meta.active"), false)
+
+  const found = structkit.findDeep(value, { path: "queue.regions[1].city" })
+  assert.equal(found.value, "Mumbai")
+  assert.equal(found.depth, 3)
+  assert.equal(found.pathDepth, 4)
+
+  const scoped = structkit.findDeep(value, { key: "city", depth: 2 }, {
+    fromPath: "queue",
+    includeContainers: false,
+  })
+  assert.equal(scoped.value, "Pune")
+  assert.equal(scoped.pathDepth, 3)
+
+  const filtered = structkit.filterDeep(value, { key: "city" })
+  assert.equal(filtered.length, 2)
+
+  const paths = structkit.findPaths(value, { includes: "joined" })
+  assert.deepEqual(paths, ["queue.stats.joined"])
+
+  const deepest = structkit.findDeep(value, { key: "active" }, {
+    includeContainers: false,
+    greedy: "deepest",
+  })
+  assert.equal(deepest.path, "queue.regions[1].meta.active")
+
+  const updated = structkit.mapDeep(value, { key: "city" }, (city) => city.toUpperCase())
+  assert.deepEqual(updated.queue.regions.map((item) => item.city), ["PUNE", "MUMBAI"])
+
+  const inserted = structkit.insertDeep(value, { path: "queue.regions" }, {
+    city: "Nagpur",
+    meta: { active: true },
+  }, { index: 1 })
+  assert.equal(inserted.queue.regions[1].city, "Nagpur")
+  assert.equal(value.queue.regions.length, 2)
+
+  const removed = structkit.removeDeep(value, { path: "queue.regions[1].meta.active" })
+  assert.equal(structkit.has(removed, "queue.regions[1].meta.active"), false)
+  assert.equal(structkit.has(value, "queue.regions[1].meta.active"), true)
+})
+
+test("deep helpers can handle long chains without stack overflow and stop on limits", () => {
+  const root = {}
+  let current = root
+
+  for (let index = 0; index < 1500; index += 1) {
+    current.next = { depth: index }
+    current = current.next
+  }
+
+  const found = structkit.findDeep(root, { key: "depth", depth: 1500 }, {
+    includeContainers: false,
+    maxDepth: 1500,
+  })
+  assert.equal(found.value, 1499)
+  assert.equal(found.pathDepth, 1501)
+
+  assert.throws(() => {
+    [...structkit.iterateDeep(root, {
+      maxNodes: 100,
+    })]
+  }, /maxNodes/)
+})