@nyaomaru/divider 1.7.3 → 1.8.0

package/README.md

@@ -130,6 +130,22 @@ const result = dividerLoop('abcdefghij', 3);
 // Supports flatten option for string[]
 const result2 = dividerLoop(['hello', 'world'], 2, { flatten: true });
 // ['he', 'll', 'ow', 'or', 'ld']
+
+// You can also control where to start dividing using `startOffset`
+const result3 = dividerLoop('abcdefghij', 3, { startOffset: 1 });
+// ['abcd', 'efg', 'hij']
+
+// Combine with flatten and trim
+const result4 = dividerLoop(['  hello ', 'world  '], 2, {
+  flatten: true,
+  trim: true,
+  startOffset: 1,
+});
+// ['h', 'el', 'lo', 'wor', 'ld']
+
+// Limit the number of chunks using maxChunks
+const result5 = dividerLoop('abcdefghij', 3, { maxChunks: 2 });
+// ['abc', 'defghij']
 ```
 
 ### 📌 `dividerNumberString()` Usage
@@ -150,22 +166,22 @@ const result3 = dividerNumberString(['abc123', '45z'], { flatten: true });
 // ['abc', '123', '45', 'z']
 ```
 
-## 🎯 Options
+## 🎯 General Options
 
-| Option         | Type      | Default | Description                                                               |
-| -------------- | ----------| ------- | ------------------------------------------------------------------------- |
-| `flatten`      | `boolean` | `false` | If `true`, the resulting nested arrays are flattened into a single array. |
-| `trim`         | `boolean` | `false` | If `true`, trims whitespace from each divided segment.                    |
-| `excludeEmpty` | `boolean` | `false` | If `true`, removes empty strings or strings with only whitespace.         |
+| Option    | Type                                 | Default  | Description                                                               |
+| --------- | ------------------------------------ | -------- | ------------------------------------------------------------------------- |
+| `flatten` | `boolean`                            | `false`  | If `true`, the resulting nested arrays are flattened into a single array. |
+| `trim`    | `boolean`                            | `false`  | If `true`, trims whitespace from each divided segment.                    |
+| `exclude` | `'none'  /  'empty'  / 'whitespace'` | `'none'` | See detailed explanation below                                            |
 
 ### `flatten` (default: `false`)
 
 ```ts
 const words = ['hello', 'world'];
-const result1 = divider(words, 2);
+const result = divider(words, 2);
 // [['he', 'llo'], ['wo', 'rld']]
 
-const result2 = divider(words, 2, { flatten: true });
+const result = divider(words, 2, { flatten: true });
 // ['he', 'llo', 'wo', 'rld']
 ```
 
@@ -175,28 +191,47 @@ const result2 = divider(words, 2, { flatten: true });
 const result = divider('  hello world  ', 7, { trim: true });
 // ['hello', 'world']
 
-const result2 = divider(['  a  ', ' b  c '], ' ', {
+const result = divider(['  a  ', ' b  c '], ' ', {
   flatten: true,
   trim: true,
 });
 // ['a', 'b', 'c']
 ```
 
-### `excludeEmpty` (default: `false`)
+### `exclude` (default: `'none'`)
+
+| Option         | Description                                                              |
+| -------------- | ------------------------------------------------------------------------ |
+| `'none'`       | Do not exclude any segments (all results are kept).                      |
+| `'empty'`      | Exclude empty strings (`''`).                                            |
+| `'whitespace'` | Exclude strings that contain only whitespace characters (e.g., `'   '`). |
+
+Control how segments like empty strings (`''`) or whitespace-only strings (`'   '`) are handled.
 
 ```ts
-// Remove empty strings or strings with only spaces
-const result = divider('a, ,b', ',', { trim: true, excludeEmpty: true });
+// Remove truly empty strings
+const result = divider('a,,b', ',', { exclude: 'empty' });
 // ['a', 'b']
 
-const result2 = divider(['  a  ', ' ', '  b'], ' ', {
-  flatten: true,
+// Remove both empty and whitespace-only strings
+const result = divider('a, ,b', ',', { exclude: 'whitespace' });
+// ['a', 'b']
+
+// You can combine with `trim` for clearer results
+const result = divider('a, ,b', ',', {
   trim: true,
-  excludeEmpty: true,
+  exclude: 'whitespace',
 });
 // ['a', 'b']
 ```
 
+## Special Options
+
+| Option        | Type     | Default | Description                                                                                             |
+| ------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `startOffset` | `number` | `0`     | Starting index offset when dividing into chunks (only for `dividerLoop`)                                |
+| `maxChunks`   | `number` | `∞`     | Maximum number of chunks allowed. Extra chunks are joined into the last chunk. (only for `dividerLoop`) |
+
 ## 💡 Features
 
 - 🧩 Flexible Division: Index-based and string-based separators

package/dist/index.cjs

@@ -28,9 +28,6 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/utils/constants.ts
-var dividerOptionKeys = ["flatten", "trim", "excludeEmpty"];
-
 // src/utils/is.ts
 function isString(arg) {
   return typeof arg === "string";
@@ -40,7 +37,7 @@ function isNumber(arg) {
 }
 function isOptions(arg) {
   if (typeof arg !== "object" || arg === null) return false;
-  return dividerOptionKeys.some((key) => key in arg);
+  return "flatten" in arg || "trim" in arg || "exclude" in arg;
 }
 function isEmptyArray(input) {
   return Array.isArray(input) && input.length === 0;
@@ -60,6 +57,12 @@ function isNestedStringArray(input) {
 function isWhitespaceOnly(s) {
   return s.trim() === "";
 }
+function isEmptyString(s) {
+  return s === "";
+}
+function isNoneMode(mode) {
+  return mode === "none";
+}
 
 // src/utils/regex.ts
 var regexCache = /* @__PURE__ */ new Map();
@@ -116,6 +119,13 @@ function ensureStringArray(input) {
   return isString(input) ? [input] : input;
 }
 
+// src/utils/exclude-predicate.ts
+var excludePredicateMap = {
+  none: () => true,
+  empty: (s) => !isEmptyString(s),
+  whitespace: (s) => !isWhitespaceOnly(s)
+};
+
 // src/utils/option.ts
 function extractOptions(args) {
   const clonedArgs = [...args];
@@ -138,8 +148,15 @@ function applyDividerOptions(result, options) {
   if (options.flatten) {
     output = output.flat();
   }
-  if (options.excludeEmpty) {
-    output = isNestedStringArray(output) ? output.filter((arr) => arr.some((s) => !isWhitespaceOnly(s))) : output.filter((s) => !isWhitespaceOnly(s));
+  if (!isNoneMode(options.exclude)) {
+    const exclude = options.exclude ?? "none";
+    let shouldKeep = () => true;
+    if (exclude in excludePredicateMap) {
+      shouldKeep = excludePredicateMap[exclude];
+    }
+    const filterNested = (arr) => arr.map((row) => row.filter(shouldKeep)).filter((row) => row.length > 0);
+    const filterFlat = (arr) => arr.filter(shouldKeep);
+    output = isNestedStringArray(output) ? filterNested(output) : filterFlat(output);
   }
   return output;
 }
@@ -205,7 +222,17 @@ function dividerLoop(input, size, options) {
     console.warn("dividerLoop: chunk size must be a positive number");
     return [];
   }
-  const applyChunking = (str) => divider(str, ...generateIndexes(str, size, options?.startOffset ?? 0));
+  const { startOffset = 0, maxChunks } = options ?? {};
+  const applyChunking = (str) => {
+    let chunks = divider(str, ...generateIndexes(str, size, startOffset));
+    const shouldTruncateChunks = isNumber(maxChunks) && maxChunks > 0 && chunks.length > maxChunks;
+    if (shouldTruncateChunks) {
+      const head = chunks.slice(0, maxChunks - 1);
+      const tail = chunks.slice(maxChunks - 1).join("");
+      chunks = [...head, tail];
+    }
+    return chunks;
+  };
   if (isString(input)) {
     const result2 = applyChunking(input);
     return applyDividerOptions(result2, options ?? {});

package/dist/index.d.cts

@@ -1,10 +1,13 @@
-declare const dividerOptionKeys: readonly ["flatten", "trim", "excludeEmpty"];
-
-type DividerOptionKey = (typeof dividerOptionKeys)[number];
+type DividerExcludeMode = 'none' | 'empty' | 'whitespace';
 type DividerResult<T extends string | string[]> = T extends string ? string[] : string[][];
-type DividerOptions = Partial<Record<DividerOptionKey, boolean>>;
+type DividerOptions = {
+    flatten?: boolean;
+    trim?: boolean;
+    exclude?: DividerExcludeMode;
+};
 type DividerLoopOptions = DividerOptions & {
     startOffset?: number;
+    maxChunks?: number;
 };
 type DividerSeparators = (number | string)[];
 type DividerArgs = DividerSeparators | [...DividerSeparators, DividerOptions];
@@ -19,4 +22,4 @@ declare function dividerLoop<T extends string | string[]>(input: T, size: number
 
 declare function dividerNumberString<T extends string | string[]>(input: T, options?: DividerOptions): DividerResult<T>;
 
-export { type DividerArgs, type DividerLoopOptions, type DividerOptionKey, type DividerOptions, type DividerResult, type DividerSeparators, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };
+export { type DividerArgs, type DividerExcludeMode, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparators, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-declare const dividerOptionKeys: readonly ["flatten", "trim", "excludeEmpty"];
-
-type DividerOptionKey = (typeof dividerOptionKeys)[number];
+type DividerExcludeMode = 'none' | 'empty' | 'whitespace';
 type DividerResult<T extends string | string[]> = T extends string ? string[] : string[][];
-type DividerOptions = Partial<Record<DividerOptionKey, boolean>>;
+type DividerOptions = {
+    flatten?: boolean;
+    trim?: boolean;
+    exclude?: DividerExcludeMode;
+};
 type DividerLoopOptions = DividerOptions & {
     startOffset?: number;
+    maxChunks?: number;
 };
 type DividerSeparators = (number | string)[];
 type DividerArgs = DividerSeparators | [...DividerSeparators, DividerOptions];
@@ -19,4 +22,4 @@ declare function dividerLoop<T extends string | string[]>(input: T, size: number
 
 declare function dividerNumberString<T extends string | string[]>(input: T, options?: DividerOptions): DividerResult<T>;
 
-export { type DividerArgs, type DividerLoopOptions, type DividerOptionKey, type DividerOptions, type DividerResult, type DividerSeparators, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };
+export { type DividerArgs, type DividerExcludeMode, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparators, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };

package/dist/index.js

@@ -1,6 +1,3 @@
-// src/utils/constants.ts
-var dividerOptionKeys = ["flatten", "trim", "excludeEmpty"];
-
 // src/utils/is.ts
 function isString(arg) {
   return typeof arg === "string";
@@ -10,7 +7,7 @@ function isNumber(arg) {
 }
 function isOptions(arg) {
   if (typeof arg !== "object" || arg === null) return false;
-  return dividerOptionKeys.some((key) => key in arg);
+  return "flatten" in arg || "trim" in arg || "exclude" in arg;
 }
 function isEmptyArray(input) {
   return Array.isArray(input) && input.length === 0;
@@ -30,6 +27,12 @@ function isNestedStringArray(input) {
 function isWhitespaceOnly(s) {
   return s.trim() === "";
 }
+function isEmptyString(s) {
+  return s === "";
+}
+function isNoneMode(mode) {
+  return mode === "none";
+}
 
 // src/utils/regex.ts
 var regexCache = /* @__PURE__ */ new Map();
@@ -86,6 +89,13 @@ function ensureStringArray(input) {
   return isString(input) ? [input] : input;
 }
 
+// src/utils/exclude-predicate.ts
+var excludePredicateMap = {
+  none: () => true,
+  empty: (s) => !isEmptyString(s),
+  whitespace: (s) => !isWhitespaceOnly(s)
+};
+
 // src/utils/option.ts
 function extractOptions(args) {
   const clonedArgs = [...args];
@@ -108,8 +118,15 @@ function applyDividerOptions(result, options) {
   if (options.flatten) {
     output = output.flat();
   }
-  if (options.excludeEmpty) {
-    output = isNestedStringArray(output) ? output.filter((arr) => arr.some((s) => !isWhitespaceOnly(s))) : output.filter((s) => !isWhitespaceOnly(s));
+  if (!isNoneMode(options.exclude)) {
+    const exclude = options.exclude ?? "none";
+    let shouldKeep = () => true;
+    if (exclude in excludePredicateMap) {
+      shouldKeep = excludePredicateMap[exclude];
+    }
+    const filterNested = (arr) => arr.map((row) => row.filter(shouldKeep)).filter((row) => row.length > 0);
+    const filterFlat = (arr) => arr.filter(shouldKeep);
+    output = isNestedStringArray(output) ? filterNested(output) : filterFlat(output);
   }
   return output;
 }
@@ -175,7 +192,17 @@ function dividerLoop(input, size, options) {
     console.warn("dividerLoop: chunk size must be a positive number");
     return [];
   }
-  const applyChunking = (str) => divider(str, ...generateIndexes(str, size, options?.startOffset ?? 0));
+  const { startOffset = 0, maxChunks } = options ?? {};
+  const applyChunking = (str) => {
+    let chunks = divider(str, ...generateIndexes(str, size, startOffset));
+    const shouldTruncateChunks = isNumber(maxChunks) && maxChunks > 0 && chunks.length > maxChunks;
+    if (shouldTruncateChunks) {
+      const head = chunks.slice(0, maxChunks - 1);
+      const tail = chunks.slice(maxChunks - 1).join("");
+      chunks = [...head, tail];
+    }
+    return chunks;
+  };
   if (isString(input)) {
     const result2 = applyChunking(input);
     return applyDividerOptions(result2, options ?? {});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nyaomaru/divider",
   "type": "module",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "To divide string or string[] with a given separator",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",