To divide string or string[] with a given separator
npm install @nyaomaru/divider

A simple utility to divide a string or string[] based on given indexes or delimiters.
You can install @nyaomaru/divider using your favorite package manager:
``shUsing pnpm (recommended)
pnpm install @nyaomaru/divider
$3
This package is also published on JSR and works in Deno and Bun without a bundler.
`ts
// Deno/Bun: import directly from JSR
import { divider } from 'jsr:@nyaomaru/divider';
`Version pinning examples:
`ts
// Pin a major version (recommended)
import { divider } from 'jsr:@nyaomaru/divider@^1';// Or pin an exact version
import { divider } from 'jsr:@nyaomaru/divider@1.9.4';
`For Bun, you can also add it to your project manifest:
`sh
Pin a major version in Bun
bun add jsr:@nyaomaru/divider@^1
`๐ Documentation
- ๐ Guide: https://divider-docs.vercel.app
- ๐งช API Reference: https://nyaomaru.github.io/divider/
๐ Usage
divider allows you to divide a string or an array of strings using index positions or delimiters.$3
`ts
import { divider } from '@nyaomaru/divider';// Divide a string by index positions
const helloArray = divider('hello', 1, 3);
// ['h', 'el', 'lo']
const [hello1, hello2, ...restHello] = divider('hello', 1, 3, 4);
// hello1 = 'h'
// hello2 = 'el'
// restHello = ['l', 'o']
// Divide a string using a character separator
const divideWithString = divider('hello', 'e');
// ['h', 'llo']
const divideWithMultipleString = divider('hello', 'l');
// ['he', 'o']
// Divide an array of strings
const words = ['hello', 'world'];
const dividedWords = divider(words, 2);
// [['he', 'llo'], ['wo', 'rld']]
const dividedWordsWithFlattenOption = divider(words, 2, { flatten: true });
// ['he', 'llo', 'wo', 'rld']
`$3
`ts
// Mixed usage of indexes and characters
const complexDivide = divider('hello world', 3, 'o');
// ['hel', 'l', ' w', 'rld']// Nested array handling
const nestedArray = divider(['hello', 'new world'], ' ', 2);
// [['he', 'llo'], ['ne', 'w wor', 'ld']]
// Flatten option to get a single array
const flatArray = divider(['hello', 'new world'], ' ', 2, { flatten: true });
// ['he', 'llo', 'ne', 'w', 'wor', 'ld']
`$3
dividerFirst() returns only the first divided element from the result.`ts
import { dividerFirst } from '@nyaomaru/divider';const firstElement = dividerFirst('hello world', ' ');
// 'hello'
const firstArrayElement = dividerFirst(['hello', 'world'], 2);
// 'he'
`$3
dividerLast() returns only the last divided element from the result.`ts
import { dividerLast } from '@nyaomaru/divider';const lastElement = dividerLast('hello world', ' ');
// 'world'
const lastArrayElement = dividerLast(['hello', 'world'], 2);
// 'rld'
`$3
`ts
import { dividerLoop } from '@nyaomaru/divider';// Divide string into chunks of given size
const result = dividerLoop('abcdefghij', 3);
// ['abc', 'def', 'ghi', 'j']
// 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']
`$3
`ts
import { dividerNumberString } from '@nyaomaru/divider';// Divide numbers and letters from a string
const result = dividerNumberString('abc123def456');
// ['abc', '123', 'def', '456']
// Divide each string in a string[]
const result2 = dividerNumberString(['abc123', '45z']);
// [['abc', '123'], ['45', 'z']]
// Flatten option
const result3 = dividerNumberString(['abc123', '45z'], { flatten: true });
// ['abc', '123', '45', 'z']
`$3
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 \| |
| queryDivider | Divide query strings into [key, value] pairs (URL-safe) |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 |
| --------------- | ------------------------------------ | -------- | ------------------------------------------------------------------------- |
|
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. |
| preserveEmpty | boolean | false | If true, keeps empty segments produced by the split. |
| exclude | 'none' / 'empty' / 'whitespace' | 'none' | See detailed explanation below |$3
`ts
const words = ['hello', 'world'];
const result = divider(words, 2);
// [['he', 'llo'], ['wo', 'rld']]const result = divider(words, 2, { flatten: true });
// ['he', 'llo', 'wo', 'rld']
`$3
`ts
const result = divider(' hello world ', 7, { trim: true });
// ['hello', 'world']const result = divider([' a ', ' b c '], ' ', {
flatten: true,
trim: true,
});
// ['a', 'b', 'c']
`$3
`ts
const defaultResult = divider('foo,,bar,', ',');
// ['foo', 'bar']const preservedResult = divider('foo,,bar,', ',', { preserveEmpty: true });
// ['foo', '', 'bar', '']
`Keep placeholder blanks when they carry meaning (e.g., CSV cells, sparse logs, diff tooling). Combine with
exclude to filter later in the pipeline.$3
| 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 truly empty strings
const result = divider('a,,b', ',', { exclude: 'empty' });
// ['a', 'b']// Remove both empty and whitespace-only strings
const result = divider('a, ,b', ',', { exclude: 'whitespace' });
// ['a', 'b']
// You can combine with
trim for clearer results (note the trailing space)
const result = divider('a, ,b ', ',', {
trim: 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
- ๐งต Handles Nested Input: Supports both string and string[]
- ๐๏ธ Optional Behaviors: flatten, trim, preserveEmpty, exclude
- ๐ฏ Targeted Extractors: dividerFirst(), dividerLast()
- ๐ Loop Support: dividerLoop() for chunked division
- ๐ข Digit-Letter Splitter: dividerNumberString()
๐ Contributing
We welcome contributions!
Please read our CONTRIBUTING.md guide before submitting a PR.
Thank you for your contribution. ๐บ
๐ Additional Documents
- DEVELOPER.md โ Development setup and contributor guide
- CODE_OF_CONDUCT.md โ Community standards and conduct
- CHANGELOG.md โ Version history and notable changes
๐ฆ Deno / JSR Notes
- Import path alias
@/ is supported in Deno via the included deno.json import map.
- Type-check locally with Deno: deno task check (or deno check ./src/index.ts).
- Publish to JSR from a tagged commit: deno publish.
- CI: On PRs, we run deno fmt --check / deno lint / deno check / deno test.
- CI JSR publish runs deno publish when a GitHub Release is published (OIDC-based; no personal token required).
- deno test is configured to only target tests-deno/** (Bun/Jest tests are excluded).
- For local development, Deno's unstable sloppy-imports is enabled to resolve the @/ alias (this does not affect JSR publishing or consumers).
- VSCode: to enable Bun type completions, add bun-types as a dev dependency and include "bun-types" in tests-bun/tsconfig.json types (this repo is preconfigured).
- VSCode: the Deno extension is enabled only for tests-deno/ (see .vscode/settings.json), which fixes typings for jsr:@std/assert`.