@nyaomaru/divider 1.8.18 → 1.9.0

package/README.md

@@ -158,11 +158,11 @@ const result5 = dividerLoop('abcdefghij', 3, { maxChunks: 2 });
 ```ts
 import { dividerNumberString } from '@nyaomaru/divider';
 
-// Split numbers and letters from a string
+// Divide numbers and letters from a string
 const result = dividerNumberString('abc123def456');
 // ['abc', '123', 'def', '456']
 
-// Split each string in a string[]
+// Divide each string in a string[]
 const result2 = dividerNumberString(['abc123', '45z']);
 // [['abc', '123'], ['45', 'z']]
 
@@ -171,6 +171,18 @@ const result3 = dividerNumberString(['abc123', '45z'], { flatten: true });
 // ['abc', '123', '45', 'z']
 ```
 
+### 📌 Presets
+
+Some common use cases are wrapped as presets for convenience.
+
+| Preset name    | Description                                               |
+| -------------- | --------------------------------------------------------- |
+| `emailDivider` | Divide email into [local-part, domain] (by '@')           |
+| `csvDivider`   | Divide comma-separated strings, with quoted field support |
+| `pathDivider`  | Divide file paths by / or \|                              |
+
+[Presets detail](src/presets/README.md)
+
 ## 🎯 General Options
 
 | Option    | Type                                 | Default  | Description                                                               |

package/dist/index.cjs

@@ -20,11 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  csvDivider: () => csvDivider,
   divider: () => divider,
   dividerFirst: () => dividerFirst,
   dividerLast: () => dividerLast,
   dividerLoop: () => dividerLoop,
-  dividerNumberString: () => dividerNumberString
+  dividerNumberString: () => dividerNumberString,
+  emailDivider: () => emailDivider,
+  pathDivider: () => pathDivider
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -46,6 +49,12 @@ var PERFORMANCE_CONSTANTS = {
   DEFAULT_MAX_CHUNKS: 0
 };
 var CACHE_KEY_SEPARATOR = "\0";
+var WHITE_SPACE = " ";
+var TAB = "	";
+var PATH_SEPARATORS = {
+  SLASH: "/",
+  ALT: "|"
+};
 
 // src/utils/is.ts
 function isString(arg) {
@@ -362,11 +371,121 @@ function dividerNumberString(input, options) {
   const result = isString(input) ? divideNumberString(input) : input.map(divideNumberString);
   return applyDividerOptions(result, options ?? {});
 }
+
+// src/utils/quoted.ts
+function dividePreserve(input, separator) {
+  if (input === "") return [""];
+  const divided = divider(input, separator);
+  return divided.join(separator) === input ? divided : input.split(separator);
+}
+function countUnescaped(text, quote) {
+  const pair = quote + quote;
+  let count = 0;
+  for (const chunk of dividePreserve(text, pair)) {
+    count += dividePreserve(chunk, quote).length - 1;
+  }
+  return count;
+}
+function stripOuterQuotes(text, quoteChar, { lenient = true } = {}) {
+  const escapedPair = quoteChar + quoteChar;
+  const isWhitespace = (char) => char === WHITE_SPACE || char === TAB;
+  const restoreEscapedQuotes = (fieldText) => fieldText.split(escapedPair).join(quoteChar);
+  let left = 0;
+  let right = text.length - 1;
+  while (left <= right && isWhitespace(text[left])) left++;
+  while (right >= left && isWhitespace(text[right])) right--;
+  if (left > right) return restoreEscapedQuotes(text);
+  const startsWithQuote = text[left] === quoteChar;
+  if (!startsWithQuote) return restoreEscapedQuotes(text);
+  const endsWithQuote = text[right] === quoteChar;
+  if (endsWithQuote && right > left) {
+    const withoutPair = text.slice(0, left) + text.slice(left + 1, right) + text.slice(right + 1);
+    return restoreEscapedQuotes(withoutPair);
+  }
+  if (!lenient) return restoreEscapedQuotes(text);
+  let result = text.slice(0, left) + text.slice(left + 1);
+  let lastNonSpaceIndexAfterTrim = result.length - 1;
+  while (lastNonSpaceIndexAfterTrim >= 0 && isWhitespace(result[lastNonSpaceIndexAfterTrim])) {
+    lastNonSpaceIndexAfterTrim--;
+  }
+  if (lastNonSpaceIndexAfterTrim >= 0 && result[lastNonSpaceIndexAfterTrim] === quoteChar) {
+    result = result.slice(0, lastNonSpaceIndexAfterTrim) + result.slice(lastNonSpaceIndexAfterTrim + 1);
+  }
+  return restoreEscapedQuotes(result);
+}
+function quotedDivide(line, {
+  delimiter = ",",
+  quote = '"',
+  trim = false,
+  lenient = true
+} = {}) {
+  if (line === "") return [""];
+  const pieces = dividePreserve(line, delimiter);
+  const fields = [];
+  let currentFieldBuffer = "";
+  let insideQuotes = false;
+  const flush = () => {
+    let fieldValue = stripOuterQuotes(currentFieldBuffer, quote, { lenient });
+    if (trim) fieldValue = fieldValue.trim();
+    fields.push(fieldValue);
+    currentFieldBuffer = "";
+  };
+  for (const piece of pieces) {
+    currentFieldBuffer = currentFieldBuffer === "" ? piece : currentFieldBuffer + delimiter + piece;
+    insideQuotes = countUnescaped(currentFieldBuffer, quote) % 2 === 1;
+    if (!insideQuotes) flush();
+  }
+  if (currentFieldBuffer !== "") flush();
+  return fields;
+}
+
+// src/presets/csv-divider.ts
+function csvDivider(line, options = {}) {
+  const { delimiter = ",", quoteChar = '"', trim = false } = options;
+  return quotedDivide(line, {
+    delimiter,
+    quote: quoteChar,
+    trim,
+    lenient: true
+  });
+}
+
+// src/presets/email-divider.ts
+var MAX_EMAIL_PARTS = 2;
+function emailDivider(input, options = {}) {
+  const { splitTLD, ...dividerOptions } = options;
+  const result = divider(input, "@", dividerOptions);
+  if (result.length > MAX_EMAIL_PARTS) {
+    console.warn(
+      `[divider/emailDivider] Too many "@" symbols in "${input}". Expected at most one.`
+    );
+  }
+  if (splitTLD && result.length === MAX_EMAIL_PARTS) {
+    const [local, domain] = result;
+    const domainParts = divider(domain, ".", dividerOptions);
+    return [local, ...domainParts];
+  }
+  return result;
+}
+
+// src/presets/path-divider.ts
+function pathDivider(input, options = {}) {
+  const { trim = false, collapse = true } = options;
+  if (input === "") return [""];
+  const segments = collapse ? divider(input, PATH_SEPARATORS.SLASH, PATH_SEPARATORS.ALT) : dividePreserve(input, PATH_SEPARATORS.ALT).flatMap(
+    (part) => dividePreserve(part, PATH_SEPARATORS.SLASH)
+  );
+  const maybeTrimmed = trim ? segments.map((segment) => segment.trim()) : segments;
+  return collapse ? maybeTrimmed.filter((segment) => segment !== "") : maybeTrimmed;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  csvDivider,
   divider,
   dividerFirst,
   dividerLast,
   dividerLoop,
-  dividerNumberString
+  dividerNumberString,
+  emailDivider,
+  pathDivider
 });

package/dist/index.d.cts

@@ -21,20 +21,20 @@ type DividerInput = StringInput | StringArrayInput;
 type DividerStringResult = string[];
 type DividerArrayResult = string[][];
 type DividerResult<T extends DividerInput> = T extends StringInput ? DividerStringResult : DividerArrayResult;
-interface DividerOptions {
+type DividerOptions = {
     /** If true, flattens nested arrays into a single array */
     flatten?: boolean;
     /** If true, trims whitespace from each divided segment */
     trim?: boolean;
     /** Controls how empty or whitespace segments are handled */
     exclude?: DividerExcludeMode;
-}
-interface DividerLoopOptions extends DividerOptions {
+};
+type DividerLoopOptions = DividerOptions & {
     /** Starting position for the division (0-based) */
     startOffset?: number;
     /** Maximum number of chunks to produce */
     maxChunks?: number;
-}
+};
 type NumericSeparator = number;
 type StringSeparator = string;
 type DividerSeparator = NumericSeparator | StringSeparator;
@@ -115,4 +115,50 @@ 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 DividerArrayResult, type DividerExcludeMode, type DividerInput, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };
+type EmailDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Split top-level domain from the rest of the email address. */
+    splitTLD?: boolean;
+};
+type CsvDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Character used for quoting values. */
+    quoteChar?: string;
+    /** Character used to separate CSV fields. */
+    delimiter?: string;
+};
+type PathDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Collapse empty segments produced by leading/trailing or repeated separators. */
+    collapse?: boolean;
+};
+
+/**
+ * Divides a CSV line into an array of fields, handling quoted values appropriately.
+ *
+ * @param line - The CSV line string to be divided into fields
+ * @param options - Configuration options for CSV parsing
+ * @param options.delimiter - The character used to separate fields (default: ',')
+ * @param options.quoteChar - The character used to quote fields containing delimiters or newlines (default: '"')
+ * @param options.trim - Whether to trim whitespace from field values (default: false)
+ * @returns A DividerStringResult containing the parsed CSV fields
+ */
+declare function csvDivider(line: string, options?: CsvDividerOptions): DividerStringResult;
+
+/**
+ * Divides an email address string at the "@" symbol into its local and domain parts.
+ *
+ * @param input - The email address string to divide
+ * @param options - Optional configuration for the divider operation
+ * @returns A DividerStringResult containing the divided parts of the email address
+ */
+declare function emailDivider(input: string, options?: EmailDividerOptions): DividerStringResult;
+
+/**
+ * Divides a path string into segments using path separators.
+ * @param input - The path string to divide
+ * @param options - Configuration options for path division
+ * @param options.trim - Whether to trim whitespace from segments
+ * @param options.collapse - Whether to collapse consecutive separators and filter empty segments
+ * @returns Array of path segments
+ */
+declare function pathDivider(input: string, options?: PathDividerOptions): DividerStringResult;
+
+export { type DividerArgs, type DividerArrayResult, type DividerExcludeMode, type DividerInput, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider };

package/dist/index.d.ts

@@ -21,20 +21,20 @@ type DividerInput = StringInput | StringArrayInput;
 type DividerStringResult = string[];
 type DividerArrayResult = string[][];
 type DividerResult<T extends DividerInput> = T extends StringInput ? DividerStringResult : DividerArrayResult;
-interface DividerOptions {
+type DividerOptions = {
     /** If true, flattens nested arrays into a single array */
     flatten?: boolean;
     /** If true, trims whitespace from each divided segment */
     trim?: boolean;
     /** Controls how empty or whitespace segments are handled */
     exclude?: DividerExcludeMode;
-}
-interface DividerLoopOptions extends DividerOptions {
+};
+type DividerLoopOptions = DividerOptions & {
     /** Starting position for the division (0-based) */
     startOffset?: number;
     /** Maximum number of chunks to produce */
     maxChunks?: number;
-}
+};
 type NumericSeparator = number;
 type StringSeparator = string;
 type DividerSeparator = NumericSeparator | StringSeparator;
@@ -115,4 +115,50 @@ 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 DividerArrayResult, type DividerExcludeMode, type DividerInput, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString };
+type EmailDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Split top-level domain from the rest of the email address. */
+    splitTLD?: boolean;
+};
+type CsvDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Character used for quoting values. */
+    quoteChar?: string;
+    /** Character used to separate CSV fields. */
+    delimiter?: string;
+};
+type PathDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Collapse empty segments produced by leading/trailing or repeated separators. */
+    collapse?: boolean;
+};
+
+/**
+ * Divides a CSV line into an array of fields, handling quoted values appropriately.
+ *
+ * @param line - The CSV line string to be divided into fields
+ * @param options - Configuration options for CSV parsing
+ * @param options.delimiter - The character used to separate fields (default: ',')
+ * @param options.quoteChar - The character used to quote fields containing delimiters or newlines (default: '"')
+ * @param options.trim - Whether to trim whitespace from field values (default: false)
+ * @returns A DividerStringResult containing the parsed CSV fields
+ */
+declare function csvDivider(line: string, options?: CsvDividerOptions): DividerStringResult;
+
+/**
+ * Divides an email address string at the "@" symbol into its local and domain parts.
+ *
+ * @param input - The email address string to divide
+ * @param options - Optional configuration for the divider operation
+ * @returns A DividerStringResult containing the divided parts of the email address
+ */
+declare function emailDivider(input: string, options?: EmailDividerOptions): DividerStringResult;
+
+/**
+ * Divides a path string into segments using path separators.
+ * @param input - The path string to divide
+ * @param options - Configuration options for path division
+ * @param options.trim - Whether to trim whitespace from segments
+ * @param options.collapse - Whether to collapse consecutive separators and filter empty segments
+ * @returns Array of path segments
+ */
+declare function pathDivider(input: string, options?: PathDividerOptions): DividerStringResult;
+
+export { type DividerArgs, type DividerArrayResult, type DividerExcludeMode, type DividerInput, type DividerLoopOptions, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider };

package/dist/index.js

@@ -16,6 +16,12 @@ var PERFORMANCE_CONSTANTS = {
   DEFAULT_MAX_CHUNKS: 0
 };
 var CACHE_KEY_SEPARATOR = "\0";
+var WHITE_SPACE = " ";
+var TAB = "	";
+var PATH_SEPARATORS = {
+  SLASH: "/",
+  ALT: "|"
+};
 
 // src/utils/is.ts
 function isString(arg) {
@@ -332,10 +338,120 @@ function dividerNumberString(input, options) {
   const result = isString(input) ? divideNumberString(input) : input.map(divideNumberString);
   return applyDividerOptions(result, options ?? {});
 }
+
+// src/utils/quoted.ts
+function dividePreserve(input, separator) {
+  if (input === "") return [""];
+  const divided = divider(input, separator);
+  return divided.join(separator) === input ? divided : input.split(separator);
+}
+function countUnescaped(text, quote) {
+  const pair = quote + quote;
+  let count = 0;
+  for (const chunk of dividePreserve(text, pair)) {
+    count += dividePreserve(chunk, quote).length - 1;
+  }
+  return count;
+}
+function stripOuterQuotes(text, quoteChar, { lenient = true } = {}) {
+  const escapedPair = quoteChar + quoteChar;
+  const isWhitespace = (char) => char === WHITE_SPACE || char === TAB;
+  const restoreEscapedQuotes = (fieldText) => fieldText.split(escapedPair).join(quoteChar);
+  let left = 0;
+  let right = text.length - 1;
+  while (left <= right && isWhitespace(text[left])) left++;
+  while (right >= left && isWhitespace(text[right])) right--;
+  if (left > right) return restoreEscapedQuotes(text);
+  const startsWithQuote = text[left] === quoteChar;
+  if (!startsWithQuote) return restoreEscapedQuotes(text);
+  const endsWithQuote = text[right] === quoteChar;
+  if (endsWithQuote && right > left) {
+    const withoutPair = text.slice(0, left) + text.slice(left + 1, right) + text.slice(right + 1);
+    return restoreEscapedQuotes(withoutPair);
+  }
+  if (!lenient) return restoreEscapedQuotes(text);
+  let result = text.slice(0, left) + text.slice(left + 1);
+  let lastNonSpaceIndexAfterTrim = result.length - 1;
+  while (lastNonSpaceIndexAfterTrim >= 0 && isWhitespace(result[lastNonSpaceIndexAfterTrim])) {
+    lastNonSpaceIndexAfterTrim--;
+  }
+  if (lastNonSpaceIndexAfterTrim >= 0 && result[lastNonSpaceIndexAfterTrim] === quoteChar) {
+    result = result.slice(0, lastNonSpaceIndexAfterTrim) + result.slice(lastNonSpaceIndexAfterTrim + 1);
+  }
+  return restoreEscapedQuotes(result);
+}
+function quotedDivide(line, {
+  delimiter = ",",
+  quote = '"',
+  trim = false,
+  lenient = true
+} = {}) {
+  if (line === "") return [""];
+  const pieces = dividePreserve(line, delimiter);
+  const fields = [];
+  let currentFieldBuffer = "";
+  let insideQuotes = false;
+  const flush = () => {
+    let fieldValue = stripOuterQuotes(currentFieldBuffer, quote, { lenient });
+    if (trim) fieldValue = fieldValue.trim();
+    fields.push(fieldValue);
+    currentFieldBuffer = "";
+  };
+  for (const piece of pieces) {
+    currentFieldBuffer = currentFieldBuffer === "" ? piece : currentFieldBuffer + delimiter + piece;
+    insideQuotes = countUnescaped(currentFieldBuffer, quote) % 2 === 1;
+    if (!insideQuotes) flush();
+  }
+  if (currentFieldBuffer !== "") flush();
+  return fields;
+}
+
+// src/presets/csv-divider.ts
+function csvDivider(line, options = {}) {
+  const { delimiter = ",", quoteChar = '"', trim = false } = options;
+  return quotedDivide(line, {
+    delimiter,
+    quote: quoteChar,
+    trim,
+    lenient: true
+  });
+}
+
+// src/presets/email-divider.ts
+var MAX_EMAIL_PARTS = 2;
+function emailDivider(input, options = {}) {
+  const { splitTLD, ...dividerOptions } = options;
+  const result = divider(input, "@", dividerOptions);
+  if (result.length > MAX_EMAIL_PARTS) {
+    console.warn(
+      `[divider/emailDivider] Too many "@" symbols in "${input}". Expected at most one.`
+    );
+  }
+  if (splitTLD && result.length === MAX_EMAIL_PARTS) {
+    const [local, domain] = result;
+    const domainParts = divider(domain, ".", dividerOptions);
+    return [local, ...domainParts];
+  }
+  return result;
+}
+
+// src/presets/path-divider.ts
+function pathDivider(input, options = {}) {
+  const { trim = false, collapse = true } = options;
+  if (input === "") return [""];
+  const segments = collapse ? divider(input, PATH_SEPARATORS.SLASH, PATH_SEPARATORS.ALT) : dividePreserve(input, PATH_SEPARATORS.ALT).flatMap(
+    (part) => dividePreserve(part, PATH_SEPARATORS.SLASH)
+  );
+  const maybeTrimmed = trim ? segments.map((segment) => segment.trim()) : segments;
+  return collapse ? maybeTrimmed.filter((segment) => segment !== "") : maybeTrimmed;
+}
 export {
+  csvDivider,
   divider,
   dividerFirst,
   dividerLast,
   dividerLoop,
-  dividerNumberString
+  dividerNumberString,
+  emailDivider,
+  pathDivider
 };

package/package.json

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