feat(pkg:string): added API String.toChunks

Author: fenying

packages/partials/string/src/Functions/ToChunks.test.ts

@@ -0,0 +1,30 @@
+import * as NodeTest from 'node:test';
+import * as NodeAssert from 'node:assert';
+import { toChunks} from './ToChunks';
+
+NodeTest.describe('Function String.toChunks', () => {
+
+    NodeTest.it('Should return empty if the string is empty', () => {
+
+        NodeAssert.deepStrictEqual(toChunks('', 1), []);
+        NodeAssert.deepStrictEqual(toChunks('', 1000), []);
+    });
+
+    NodeTest.it('Should throw exception if chunk size is not a positive integer', () => {
+
+        NodeAssert.throws(() => toChunks('abc', 0), RangeError);
+        NodeAssert.throws(() => toChunks('abc', -1), RangeError);
+        NodeAssert.throws(() => toChunks('abc', 1.5), RangeError);
+        NodeAssert.throws(() => toChunks('abc', NaN), RangeError);
+        NodeAssert.throws(() => toChunks('abc', Infinity), RangeError);
+    });
+
+    NodeTest.it('Should return chunks of the specified size', () => {
+
+        NodeAssert.deepStrictEqual(toChunks('abcde', 2), ['ab', 'cd', 'e']);
+        NodeAssert.deepStrictEqual(toChunks('abcdefghij', 3), ['abc', 'def', 'ghi', 'j']);
+        NodeAssert.deepStrictEqual(toChunks('abcdefghij', 5), ['abcde', 'fghij']);
+        NodeAssert.deepStrictEqual(toChunks('abcdefghij', 10), ['abcdefghij']);
+        NodeAssert.deepStrictEqual(toChunks('abcdefghi', 10), ['abcdefghi']);
+    });
+});

packages/partials/string/src/Functions/ToChunks.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright 2025 Angus.Fenying <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This function splits a string into chunks of specified size.
+ * If the string length is not a multiple of the chunk size,
+ * the last chunk will contain the remaining characters.
+ *
+ * @param text      The string to be split into chunks.
+ * @param chunkSize The size of each chunk. Must be a positive integer.
+ *
+ * @returns An array of strings, each representing a chunk of the original string.
+ * @throws RangeError if the chunk size is not a positive integer.
+ * @example `toChunks('abcdefghij', 3)` returns `['abc', 'def', 'ghi', 'j']`
+ */
+export function toChunks(text: string, chunkSize: number): string[] {
+
+    if (chunkSize <= 0 || !Number.isSafeInteger(chunkSize)) {
+
+        throw new RangeError('Chunk size must be a positive integer.');
+    }
+
+    const chunks: string[] = new Array<string>(Math.ceil(text.length / chunkSize));
+    const length = text.length;
+
+    for (let i = 0, o = 0; i < length; i += chunkSize) {
+        chunks[o++] = text.slice(i, i + chunkSize);
+    }
+
+    return chunks;
+}

packages/partials/string/src/index.ts

@@ -19,4 +19,5 @@ export * from './Functions/EvilSpace';
 export * from './Functions/Random';
 export * from './Functions/RegexpEscape';
 export * from './Functions/Html';
+export * from './Functions/ToChunks';
 export * from './Classes/UnitParser';