@nyaomaru/divider 1.9.18 → 1.9.20

package/README.md

@@ -209,9 +209,22 @@ Some common use cases are wrapped as presets for convenience.
 | `emailDivider` | Divide email into [local-part, domain] (by '@')           |
 | `csvDivider`   | Divide comma-separated strings, with quoted field support |
 | `pathDivider`  | Divide file paths by / or \|                              |
+| `queryDivider` | Divide query strings into [key, value] pairs (URL-safe)   |
 
 [Presets detail](src/presets/README.md)
 
+Example:
+
+```ts
+import { queryDivider } from '@nyaomaru/divider';
+
+queryDivider('?q=hello+world');
+// [['q', 'hello world']] // default: '+' treated as space and % decoded
+
+queryDivider('q=hello+world', { mode: 'raw' });
+// [['q', 'hello+world']] // raw mode keeps '+' and % as-is
+```
+
 ## 🎯 General Options
 
 | Option          | Type                                 | Default  | Description                                                               |

package/dist/index.cjs

@@ -27,7 +27,8 @@ __export(index_exports, {
   dividerLoop: () => dividerLoop,
   dividerNumberString: () => dividerNumberString,
   emailDivider: () => emailDivider,
-  pathDivider: () => pathDivider
+  pathDivider: () => pathDivider,
+  queryDivider: () => queryDivider
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -60,6 +61,15 @@ var PATH_SEPARATORS = {
   SLASH: "/",
   ALT: "|"
 };
+var QUERY_SEPARATORS = {
+  QUESTION_MARK: "?",
+  AMPERSAND: "&",
+  EQUALS: "="
+};
+var QUERY_DECODE_MODES = {
+  AUTO: "auto",
+  RAW: "raw"
+};
 
 // src/utils/is.ts
 function isString(value) {
@@ -509,6 +519,45 @@ function pathDivider(input, options = {}) {
   const maybeTrimmed = trim ? segments.map((segment) => segment.trim()) : segments;
   return collapse ? maybeTrimmed.filter((segment) => !isEmptyString(segment)) : maybeTrimmed;
 }
+
+// src/presets/query-divider.ts
+function tryExtractQuery(input) {
+  try {
+    const url = new URL(input);
+    return url.search.startsWith(QUERY_SEPARATORS.QUESTION_MARK) ? url.search.slice(1) : url.search;
+  } catch {
+    return input;
+  }
+}
+function stripLeadingQuestionMark(query) {
+  return query.startsWith(QUERY_SEPARATORS.QUESTION_MARK) ? query.slice(1) : query;
+}
+function splitOnFirstEquals(part) {
+  const kv = dividePreserve(part, QUERY_SEPARATORS.EQUALS);
+  if (kv.length === 1) return [kv[0] ?? "", ""];
+  return [kv[0] ?? "", kv.slice(1).join(QUERY_SEPARATORS.EQUALS)];
+}
+function decodeField(text, mode, trim) {
+  let t = text;
+  if (mode === QUERY_DECODE_MODES.AUTO) {
+    t = t.replace(/\+/g, " ");
+    try {
+      t = decodeURIComponent(t);
+    } catch {
+    }
+  }
+  if (trim) t = t.trim();
+  return t;
+}
+function queryDivider(input, { mode = QUERY_DECODE_MODES.AUTO, trim = false } = {}) {
+  if (input.length === 0) return [];
+  const query = stripLeadingQuestionMark(tryExtractQuery(input));
+  if (query.length === 0) return [];
+  return dividePreserve(query, QUERY_SEPARATORS.AMPERSAND).map((part) => {
+    const [key, value] = splitOnFirstEquals(part);
+    return [decodeField(key, mode, trim), decodeField(value, mode, trim)];
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   csvDivider,
@@ -518,5 +567,6 @@ function pathDivider(input, options = {}) {
   dividerLoop,
   dividerNumberString,
   emailDivider,
-  pathDivider
+  pathDivider,
+  queryDivider
 });

package/dist/index.d.cts

@@ -13,6 +13,13 @@ declare const DIVIDER_EXCLUDE_MODES: {
     readonly EMPTY: "empty";
     readonly WHITESPACE: "whitespace";
 };
+/**
+ * Query string decode modes.
+ */
+declare const QUERY_DECODE_MODES: {
+    readonly AUTO: "auto";
+    readonly RAW: "raw";
+};
 
 type DividerExcludeMode = (typeof DIVIDER_EXCLUDE_MODES)[keyof typeof DIVIDER_EXCLUDE_MODES];
 type StringInput = string;
@@ -158,6 +165,11 @@ type PathDividerOptions = Pick<DividerOptions, 'trim'> & {
     /** Collapse empty segments produced by leading/trailing or repeated separators. */
     collapse?: boolean;
 };
+type QueryDecodeMode = (typeof QUERY_DECODE_MODES)[keyof typeof QUERY_DECODE_MODES];
+type QueryDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Decoding mode: 'auto' applies standard URL decoding; 'raw' leaves values untouched. */
+    mode?: QueryDecodeMode;
+};
 
 /**
  * Divides a CSV line into an array of fields, handling quoted values appropriately.
@@ -190,4 +202,15 @@ declare function emailDivider(input: string, options?: EmailDividerOptions): Div
  */
 declare function pathDivider(input: string, options?: PathDividerOptions): DividerStringResult;
 
-export { type DividerArg, type DividerArgs, type DividerArrayResult, type DividerEmptyOptions, type DividerExcludeMode, type DividerInferredOptions, type DividerInput, type DividerLoopEmptyOptions, type DividerLoopOptions, type DividerLoopOptionsLike, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type ExtractedDividerOptions, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider };
+/**
+ * Divide a query string into key/value pairs.
+ * - Supports raw query (with or without leading '?').
+ * - Accepts full URLs (query extracted automatically).
+ * - Preserves empty keys/values and trailing separators.
+ * @param input Query string or full URL.
+ * @param options Parsing options: { mode?: 'auto' | 'raw'; trim?: boolean }.
+ * @returns Array of [key, value] string tuples in input order.
+ */
+declare function queryDivider(input: string, { mode, trim }?: QueryDividerOptions): DividerArrayResult;
+
+export { type DividerArg, type DividerArgs, type DividerArrayResult, type DividerEmptyOptions, type DividerExcludeMode, type DividerInferredOptions, type DividerInput, type DividerLoopEmptyOptions, type DividerLoopOptions, type DividerLoopOptionsLike, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type ExtractedDividerOptions, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider, queryDivider };

package/dist/index.d.ts

@@ -13,6 +13,13 @@ declare const DIVIDER_EXCLUDE_MODES: {
     readonly EMPTY: "empty";
     readonly WHITESPACE: "whitespace";
 };
+/**
+ * Query string decode modes.
+ */
+declare const QUERY_DECODE_MODES: {
+    readonly AUTO: "auto";
+    readonly RAW: "raw";
+};
 
 type DividerExcludeMode = (typeof DIVIDER_EXCLUDE_MODES)[keyof typeof DIVIDER_EXCLUDE_MODES];
 type StringInput = string;
@@ -158,6 +165,11 @@ type PathDividerOptions = Pick<DividerOptions, 'trim'> & {
     /** Collapse empty segments produced by leading/trailing or repeated separators. */
     collapse?: boolean;
 };
+type QueryDecodeMode = (typeof QUERY_DECODE_MODES)[keyof typeof QUERY_DECODE_MODES];
+type QueryDividerOptions = Pick<DividerOptions, 'trim'> & {
+    /** Decoding mode: 'auto' applies standard URL decoding; 'raw' leaves values untouched. */
+    mode?: QueryDecodeMode;
+};
 
 /**
  * Divides a CSV line into an array of fields, handling quoted values appropriately.
@@ -190,4 +202,15 @@ declare function emailDivider(input: string, options?: EmailDividerOptions): Div
  */
 declare function pathDivider(input: string, options?: PathDividerOptions): DividerStringResult;
 
-export { type DividerArg, type DividerArgs, type DividerArrayResult, type DividerEmptyOptions, type DividerExcludeMode, type DividerInferredOptions, type DividerInput, type DividerLoopEmptyOptions, type DividerLoopOptions, type DividerLoopOptionsLike, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type ExtractedDividerOptions, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider };
+/**
+ * Divide a query string into key/value pairs.
+ * - Supports raw query (with or without leading '?').
+ * - Accepts full URLs (query extracted automatically).
+ * - Preserves empty keys/values and trailing separators.
+ * @param input Query string or full URL.
+ * @param options Parsing options: { mode?: 'auto' | 'raw'; trim?: boolean }.
+ * @returns Array of [key, value] string tuples in input order.
+ */
+declare function queryDivider(input: string, { mode, trim }?: QueryDividerOptions): DividerArrayResult;
+
+export { type DividerArg, type DividerArgs, type DividerArrayResult, type DividerEmptyOptions, type DividerExcludeMode, type DividerInferredOptions, type DividerInput, type DividerLoopEmptyOptions, type DividerLoopOptions, type DividerLoopOptionsLike, type DividerOptions, type DividerResult, type DividerSeparator, type DividerSeparators, type DividerStringResult, type ExtractedDividerOptions, type NumericSeparator, type StringArrayInput, type StringInput, type StringSeparator, csvDivider, divider, dividerFirst, dividerLast, dividerLoop, dividerNumberString, emailDivider, pathDivider, queryDivider };

package/dist/index.js

@@ -27,6 +27,15 @@ var PATH_SEPARATORS = {
   SLASH: "/",
   ALT: "|"
 };
+var QUERY_SEPARATORS = {
+  QUESTION_MARK: "?",
+  AMPERSAND: "&",
+  EQUALS: "="
+};
+var QUERY_DECODE_MODES = {
+  AUTO: "auto",
+  RAW: "raw"
+};
 
 // src/utils/is.ts
 function isString(value) {
@@ -476,6 +485,45 @@ function pathDivider(input, options = {}) {
   const maybeTrimmed = trim ? segments.map((segment) => segment.trim()) : segments;
   return collapse ? maybeTrimmed.filter((segment) => !isEmptyString(segment)) : maybeTrimmed;
 }
+
+// src/presets/query-divider.ts
+function tryExtractQuery(input) {
+  try {
+    const url = new URL(input);
+    return url.search.startsWith(QUERY_SEPARATORS.QUESTION_MARK) ? url.search.slice(1) : url.search;
+  } catch {
+    return input;
+  }
+}
+function stripLeadingQuestionMark(query) {
+  return query.startsWith(QUERY_SEPARATORS.QUESTION_MARK) ? query.slice(1) : query;
+}
+function splitOnFirstEquals(part) {
+  const kv = dividePreserve(part, QUERY_SEPARATORS.EQUALS);
+  if (kv.length === 1) return [kv[0] ?? "", ""];
+  return [kv[0] ?? "", kv.slice(1).join(QUERY_SEPARATORS.EQUALS)];
+}
+function decodeField(text, mode, trim) {
+  let t = text;
+  if (mode === QUERY_DECODE_MODES.AUTO) {
+    t = t.replace(/\+/g, " ");
+    try {
+      t = decodeURIComponent(t);
+    } catch {
+    }
+  }
+  if (trim) t = t.trim();
+  return t;
+}
+function queryDivider(input, { mode = QUERY_DECODE_MODES.AUTO, trim = false } = {}) {
+  if (input.length === 0) return [];
+  const query = stripLeadingQuestionMark(tryExtractQuery(input));
+  if (query.length === 0) return [];
+  return dividePreserve(query, QUERY_SEPARATORS.AMPERSAND).map((part) => {
+    const [key, value] = splitOnFirstEquals(part);
+    return [decodeField(key, mode, trim), decodeField(value, mode, trim)];
+  });
+}
 export {
   csvDivider,
   divider,
@@ -484,5 +532,6 @@ export {
   dividerLoop,
   dividerNumberString,
   emailDivider,
-  pathDivider
+  pathDivider,
+  queryDivider
 };

package/package.json

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