Add a parse utility for consuming an entire input string

It seems nice to provide a function for this rather than making users
handle it themselves.

Author: mkantor

src/index.ts

@@ -1,7 +1,8 @@
 import * as combinators from './combinators.js'
 import * as constructors from './constructors.js'
+import * as parser from './parser.js'
 
-const parsing = { ...combinators, ...constructors }
+const parsing = { ...combinators, ...constructors, ...parser }
 export default parsing
 
 export * from './combinators.js'

src/parser.ts

@@ -1,4 +1,5 @@
 import type { Either, Right } from '@matt.kantor/either'
+import * as either from '@matt.kantor/either'
 
 export type InvalidInputError = {
   readonly input: string
@@ -17,3 +18,23 @@ export type Success<Output> = {
   readonly remainingInput: string
   readonly output: Output
 }
+
+/**
+ * Apply `parser` to the given `input`, requiring it to consume the entire input
+ * (all the way to the end of the string).
+ *
+ * Unlike `Parser`s, in the return value `Output` is not wrapped in `Success`
+ * (there will never be any `remainingInput`).
+ */
+export const parse = <Output>(
+  parser: Parser<Output>,
+  input: string,
+): Either<InvalidInputError, Output> =>
+  either.flatMap(parser(input), ({ remainingInput, output }) =>
+    remainingInput.length !== 0
+      ? either.makeLeft({
+          input,
+          message: 'excess content followed valid input',
+        })
+      : either.makeRight(output),
+  )