@mattwca/little-parser-lib 1.0.1 → 1.0.3

package/README.md

@@ -9,7 +9,7 @@ A lightweight, flexible TypeScript library for building parsers using parser com
 - 📝 **TypeScript First**: Full type safety and IntelliSense support
 - 🎯 **Backtracking Support**: Automatic position restoration on parse failures
 - 📦 **Zero Dependencies**: Lightweight with no external runtime dependencies
-- ✨ Packaged with [tsdown](https://tsdown.dev)
+- ✨ **Widely Compatible**: Packaged with [tsdown](https://tsdown.dev)
 
 ## Installation
 
@@ -199,6 +199,46 @@ Convenience method to tokenize and parse in one step.
 const result = runParserOnString(myParser, 'input string', tokenizer);
 ```
 
+## Utilities
+
+The library provides utility functions to help with common parser result manipulation tasks.
+
+### `unwrapResult(items)`
+
+Flattens nested arrays that result from combining parsers like `and` and `many`. This is particularly useful when you have deeply nested parser structures and need a flat array of results.
+
+```typescript
+import { unwrapResult } from '@mattwca/little-parser-lib';
+
+// Parser results can be nested
+const parser = and(
+  many(anyOf('letter')),
+  many(anyOf('digit'))
+);
+
+const result = runParser(parser, stream);
+// result.result might be: [[token1, token2], [token3, token4]]
+
+const flattened = unwrapResult(result.result);
+// flattened is: [token1, token2, token3, token4]
+```
+
+**Parameters:**
+- `items: (T | T[])[]` - An array that may contain nested arrays
+
+**Returns:**
+- `T[]` - A flattened array with all nested items extracted
+
+**Example Use Cases:**
+
+```typescript
+// Use with map to process flattened results
+const tokenParser = map(
+  and(many(anyOf('letter')), many(anyOf('digit'))),
+  (results) => unwrapResult(results).map(t => t.value).join('')
+);
+```
+
 ## Example: Simple Expression Parser
 
 ```typescript
@@ -301,6 +341,7 @@ try {
 - `runParserOnString(parser, input, tokenizer)`: Execute parser on string
 - `isSuccessfulResult(result)`: Type guard for successful results
 - `isFailedResult(result)`: Type guard for failed results
+- `unwrapResult(results)`: Unwrap nested parser results
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattwca/little-parser-lib",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -42,6 +42,7 @@
     "node": ">=14"
   },
   "repository": {
+    "type": "git",
     "url": "https://github.com/mattwca/little-parser-lib"
   }
 }

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './tokenizer';
-export * from './parser';
+export * from './parsers';
+export * from './utils';

package/src/parsers/index.ts

@@ -0,0 +1,3 @@
+export * from './parsers';
+export * from './ParsingError';
+export * from './types';

package/src/{parser/parser.ts → parsers/parsers.ts}

@@ -92,8 +92,8 @@ export function or<T>(...parsers: ParseFn<T>[]): ParseFn<T> {
 }
 
 /**
- * Applies a parser repeatedly until it fails, collecting all successful results into an array.
- * If the parser fails on the first attempt, returns a failure.
+ * Applies a parser repeatedly until it fails or doesn't make progress (move the position), collecting
+ * all successful results into an array. If the parser fails on the first attempt, returns a failure.
  */
 export function many(parser: ParseFn<any>): ParseFn<any> {
   return (tokenStream: TokenStream) => {
@@ -102,10 +102,20 @@ export function many(parser: ParseFn<any>): ParseFn<any> {
     let parseFailure = null;
 
     while (true) {
+      const positionBefore = tokenStream.position;
       tokenStream.storePosition();
 
       const result = parser(tokenStream);
+
       if (isSuccessfulResult(result)) {
+        const positionAfter = tokenStream.position;
+
+        // Check if the parser made any progress - if it didn't, we break out to avoid infinite loops.
+        if (positionAfter === positionBefore) {
+          tokenStream.restorePosition();
+          break;
+        }
+
         results.push(result.result);
         tokenStream.clearPosition();
       } else {
@@ -197,24 +207,11 @@ export function endOfInput(): ParseFn {
   };
 }
 
-export function parseName(): ParseFn<any> {
-  return (tokenStream: TokenStream) => {
-    const validTokenTypes: TokenType[] = ['letter', 'digit', 'minus', 'underscore'];
-    const parseValidToken = anyOf(...validTokenTypes);
-
-    const parser = and(anyOf('letter'), many(parseValidToken));
-    const result = parser(tokenStream);
-
-    if (isSuccessfulResult(result)) {
-      console.log(result);
-    }
-
-    return result;
-  }
-}
-
 /**
  * Transforms the result of a parser using a given mapping function.
+ * @param parser The parser whose result is to be transformed.
+ * @param mapFn A function that takes the parser's result and returns a new value.
+ * @returns A new parser that applies the mapping function to the result of the original parser.
  */
 export function map<T, U>(parser: ParseFn<T>, mapFn: (value: T) => U): ParseFn<U> {
   return (tokenStream: TokenStream) => {

package/src/utils.ts

@@ -0,0 +1,17 @@
+/**
+ * A method which unwraps a given generic array, taking each element and accumulating them, if the given item is a nested array, it is flattened into the result.
+ * Useful for flattening parser results built with the `and` and `many` combinators, which can produce nested arrays.
+ * @param items - An array of items or nested arrays of items to be unwrapped.
+ * @returns A flattened array containing all individual items.
+ */
+export const unwrapResult = <T>(items: (T | T[])[]): T[] => {
+  const result: T[] = [];
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      result.push(...unwrapResult(item));
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+};

package/src/parser/index.ts

@@ -1,3 +0,0 @@
-export * from './parser';
-export * from './ParsingError';
-export * from './types';