@typescriptprime/parsing 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,145 @@
+# @typescriptprime/parsing
+
+Lightweight helper utilities for parsing CLI-style arguments, implemented in TypeScript.
+
+This package provides two small helpers:
+
+- `PreProcessing` — trims `process.argv` to remove the node executable and optional script filename, returning the array of option tokens.
+- `PostProcessing` — parses the token list that looks like `--Name Value` into a typed options object and an array of positional arguments (everything after `--`).
+
+---
+
+## 📦 Install
+
+```bash
+npm install @typescriptprime/parsing
+```
+
+> [!NOTE]
+> This repo is authored as an ES module and fully typed with TypeScript.
+
+---
+
+## Usage
+
+Import the helpers from the package and combine them to parse `process.argv`:
+
+```typescript
+import { PreProcessing, PostProcessing } from '@typescriptprime/parsing'
+
+async function Main(Argv: string[]) {
+  // Step 1: Trim the node executable and optional script path
+  const Filtered = PreProcessing(Argv)
+
+  // Step 2: Parse CLI-style parameters into an options object and positional arguments
+  const { Options, Positional } = await PostProcessing(Filtered)
+
+  console.log('Options:', Options)
+  console.log('Positional args:', Positional)
+}
+
+Main(process.argv)
+```
+
+### Naming Convention
+
+By default, `PostProcessing` converts parameter names into PascalCase using `es-toolkit` (so `--parameter-name` becomes `ParameterName`). You can supply a custom `NamingConvention` function via `IParsingOptions`:
+
+```typescript
+import * as ESToolkit from 'es-toolkit'
+
+await PostProcessing(argv, { NamingConvention: ESToolkit.camelCase })
+// or custom:
+await PostProcessing(argv, { NamingConvention: (s) => s.replace(/^--/, '') })
+```
+
+---
+
+## ⚡ Quick Examples
+
+From `process.argv` in Node.js:
+
+```typescript
+const Argv = ['/usr/local/bin/node', '/path/to/script.js', '--enable-feature', '--parameter', 'value', '--', 'positional1', 'positional2']
+
+const Tokens = PreProcessing(Argv)
+// tokens === ['--enable-feature', '--parameter', 'value', '--', 'positional1', 'positional2']
+
+const { Options, Positional } = await PostProcessing(Tokens)
+// Options === { EnableFeature: true, Parameter: 'value' }
+// Positional === ['positional1', 'positional2']
+```
+
+Boolean flags example:
+
+```ts
+const Tokens = PreProcessing(['/usr/bin/node', '/script.js', '--flag', '--other', 'value'])
+// tokens === ['--flag', '--other', 'value']
+const { Options } = await PostProcessing(Tokens)
+// Options === { Flag: true, Other: 'value' }
+```
+
+---
+
+## API
+
+- `PreProcessing(argv: typeof process.argv): string[]`
+  - Removes the node executable and optional file argument and returns the tokens starting at the first option.
+
+- `PostProcessing<I extends JSONValue>(Args: string[], FuncOptions?: IParsingOptions): Promise<{ Options: I, Positional: string[] }>`
+  - Converts `--key value` pairs into a typed `Options` object; flags without values are treated as `true`.
+  - Stops parsing options when it hits `--` and returns the rest as `Positional` arguments.
+
+### Types
+
+- `JSONValue`, `JSONObject`, `JSONArray`, `JSONPrimitive` — standard JSON type helpers
+- `IParsingOptions` — currently supports:
+  - `NamingConvention?: (PropertyName: string) => string | Promise<string>`
+
+---
+
+## Scripts
+
+- `npm run build` — runs: `esbuild` to bundle the compiled JS and TypeScript compiler to emit declarations.
+- `npm test` — runs AVA tests.
+- `npm run lint` — runs ESLint checks.
+
+This project is published as an ES module. If you are developing locally, the following commands are useful:
+
+- `npm run build:esbuild` — bundle with esbuild (JS output)
+- `npm run build:tsc` — emit TypeScript declarations only
+
+The package `exports` are configured in `package.json` so importing the default entry works with ESM loaders.
+
+---
+
+## Tests
+
+The `tests/` directory contains unit tests for both `PreProcessing` and `PostProcessing` with AVA. They include:
+
+- PreProcessing: removes node executable and file name using different `process.argv` shapes
+- PostProcessing: parsing single/two parameters, boolean flags, and the `--` positional argument separator.
+
+Run tests with:
+
+```bash
+npm test
+```
+
+---
+
+## Project Layout
+
+- `sources/` — TypeScript source files for the package
+  - `index.ts` — entry exports
+  - `preprocessing/index.ts` — `PreProcessing` implementation
+  - `postprocessing/index.ts` — `PostProcessing` implementation
+  - `types.ts` — JSON types and `IParsingOptions`
+- `dist/` — build output (ignored in source control)
+- `tests/` — unit tests using AVA
+
+---
+
+## License
+
+Licensed under the Apache-2.0 license — see `LICENSE` for details.

package/dist/index.js

@@ -19,7 +19,7 @@ function pascalCase(str) {
 async function PostProcessing(Args, FuncOptions = {
   NamingConvention: pascalCase
 }) {
-  const Options = {};
+  const Options = /* @__PURE__ */ Object.create(null);
   const Positional = [];
   for (let I = 0; I < Args.length; I++) {
     if (Args[I] === "--") {

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../node_modules/es-toolkit/dist/string/capitalize.mjs", "../node_modules/es-toolkit/dist/string/words.mjs", "../node_modules/es-toolkit/dist/string/pascalCase.mjs", "../sources/postprocessing/index.ts", "../sources/preprocessing/index.ts"],
-  "sourcesContent": ["function capitalize(str) {\n    return (str.charAt(0).toUpperCase() + str.slice(1).toLowerCase());\n}\n\nexport { capitalize };\n", "const CASE_SPLIT_PATTERN = /\\p{Lu}?\\p{Ll}+|[0-9]+|\\p{Lu}+(?!\\p{Ll})|\\p{Emoji_Presentation}|\\p{Extended_Pictographic}|\\p{L}+/gu;\nfunction words(str) {\n    return Array.from(str.match(CASE_SPLIT_PATTERN) ?? []);\n}\n\nexport { CASE_SPLIT_PATTERN, words };\n", "import { capitalize } from './capitalize.mjs';\nimport { words } from './words.mjs';\n\nfunction pascalCase(str) {\n    const words$1 = words(str);\n    return words$1.map(word => capitalize(word)).join('');\n}\n\nexport { pascalCase };\n", "import * as ESToolkit from 'es-toolkit'\nimport type { JSONValue, IParsingOptions } from '../types.js'\n\n/**\n * Parses a list of CLI-style arguments into a structured options object and positional arguments.\n *\n * @typeParam I - The shape of the options object produced from the parsed arguments.\n * @param Args - The raw argument tokens, including option flags and positional values.\n * @param FuncOptions - Configuration for post-processing behavior, such as the naming convention transformer.\n * @returns A promise resolving to an object containing the parsed options and remaining positional arguments.\n */\nexport async function PostProcessing<I extends JSONValue>(Args: string[], FuncOptions: IParsingOptions = {\n  NamingConvention: ESToolkit.pascalCase\n}): Promise<{ Options: I, Positional: string[] }> {\n  const Options: Record<string, boolean | string> = {}\n  const Positional: string[] = []\n\n  for (let I = 0; I < Args.length; I++) {\n    if (Args[I] === '--') {\n      Positional.push(...Args.slice(I + 1))\n      break\n    }\n\n    if (Args[I].startsWith('--')) {\n      if (I + 1 === Args.length || Args[I + 1].startsWith('--')) {\n        Options[await FuncOptions.NamingConvention(Args[I])] = true\n      } else {\n        Options[await FuncOptions.NamingConvention(Args[I])] = Args[I + 1]\n        I++\n      }\n    }\n  }\n\n  return { Options: Options as I, Positional }\n}", "import type * as Process from 'node:process'\n\ntype DropFirstANDTwo<T extends readonly unknown[]> = T extends readonly [unknown, unknown, ...infer Tail] ? Tail : []\ntype DropFirst<T extends readonly unknown[]> = T extends readonly [unknown, ...infer Tail] ? Tail : []\n\n/**\n * Returns a filtered `process.argv` with only options and their values.\n * \n * @param {string} Args - A value of `process.argv`.\n * @returns A filtered `process.argv` with only options and their values.\n */\nexport function PreProcessing<Args extends typeof Process.argv>(Args: Args): DropFirstANDTwo<Args> | DropFirst<Args> {\n  if (Args[2].startsWith('--')) {\n    return Args.slice(2) as DropFirstANDTwo<Args>\n  } else {\n    return Args.slice(1) as DropFirst<Args>\n  }\n}"],
-  "mappings": ";AAAA,SAAS,WAAW,KAAK;AACrB,SAAQ,IAAI,OAAO,CAAC,EAAE,YAAY,IAAI,IAAI,MAAM,CAAC,EAAE,YAAY;AACnE;;;ACFA,IAAM,qBAAqB;AAC3B,SAAS,MAAM,KAAK;AAChB,SAAO,MAAM,KAAK,IAAI,MAAM,kBAAkB,KAAK,CAAC,CAAC;AACzD;;;ACAA,SAAS,WAAW,KAAK;AACrB,QAAM,UAAU,MAAM,GAAG;AACzB,SAAO,QAAQ,IAAI,UAAQ,WAAW,IAAI,CAAC,EAAE,KAAK,EAAE;AACxD;;;ACKA,eAAsB,eAAoC,MAAgB,cAA+B;AAAA,EACvG,kBAA4B;AAC9B,GAAkD;AAChD,QAAM,UAA4C,CAAC;AACnD,QAAM,aAAuB,CAAC;AAE9B,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,QAAI,KAAK,CAAC,MAAM,MAAM;AACpB,iBAAW,KAAK,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AACpC;AAAA,IACF;AAEA,QAAI,KAAK,CAAC,EAAE,WAAW,IAAI,GAAG;AAC5B,UAAI,IAAI,MAAM,KAAK,UAAU,KAAK,IAAI,CAAC,EAAE,WAAW,IAAI,GAAG;AACzD,gBAAQ,MAAM,YAAY,iBAAiB,KAAK,CAAC,CAAC,CAAC,IAAI;AAAA,MACzD,OAAO;AACL,gBAAQ,MAAM,YAAY,iBAAiB,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;AACjE;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAuB,WAAW;AAC7C;;;ACvBO,SAAS,cAAgD,MAAqD;AACnH,MAAI,KAAK,CAAC,EAAE,WAAW,IAAI,GAAG;AAC5B,WAAO,KAAK,MAAM,CAAC;AAAA,EACrB,OAAO;AACL,WAAO,KAAK,MAAM,CAAC;AAAA,EACrB;AACF;",
+  "sourcesContent": ["function capitalize(str) {\n    return (str.charAt(0).toUpperCase() + str.slice(1).toLowerCase());\n}\n\nexport { capitalize };\n", "const CASE_SPLIT_PATTERN = /\\p{Lu}?\\p{Ll}+|[0-9]+|\\p{Lu}+(?!\\p{Ll})|\\p{Emoji_Presentation}|\\p{Extended_Pictographic}|\\p{L}+/gu;\nfunction words(str) {\n    return Array.from(str.match(CASE_SPLIT_PATTERN) ?? []);\n}\n\nexport { CASE_SPLIT_PATTERN, words };\n", "import { capitalize } from './capitalize.mjs';\nimport { words } from './words.mjs';\n\nfunction pascalCase(str) {\n    const words$1 = words(str);\n    return words$1.map(word => capitalize(word)).join('');\n}\n\nexport { pascalCase };\n", "import * as ESToolkit from 'es-toolkit'\nimport type { JSONValue, IParsingOptions } from '../types.js'\n\n/**\n * Parses a list of CLI-style arguments into a structured options object and positional arguments.\n *\n * @typeParam I - The shape of the options object produced from the parsed arguments.\n * @param Args - The raw argument tokens, including option flags and positional values.\n * @param FuncOptions - Configuration for post-processing behavior, such as the naming convention transformer.\n * @returns A promise resolving to an object containing the parsed options and remaining positional arguments.\n */\nexport async function PostProcessing<I extends JSONValue>(Args: string[], FuncOptions: IParsingOptions = {\n  NamingConvention: ESToolkit.pascalCase\n}): Promise<{ Options: I, Positional: string[] }> {\n  const Options: Record<string, boolean | string> = Object.create(null)\n  const Positional: string[] = []\n\n  for (let I = 0; I < Args.length; I++) {\n    if (Args[I] === '--') {\n      Positional.push(...Args.slice(I + 1))\n      break\n    }\n\n    if (Args[I].startsWith('--')) {\n      if (I + 1 === Args.length || Args[I + 1].startsWith('--')) {\n        Options[await FuncOptions.NamingConvention(Args[I])] = true\n      } else {\n        Options[await FuncOptions.NamingConvention(Args[I])] = Args[I + 1]\n        I++\n      }\n    }\n  }\n\n  return { Options: Options as I, Positional }\n}", "import type * as Process from 'node:process'\n\ntype DropFirstANDTwo<T extends readonly unknown[]> = T extends readonly [unknown, unknown, ...infer Tail] ? Tail : []\ntype DropFirst<T extends readonly unknown[]> = T extends readonly [unknown, ...infer Tail] ? Tail : []\n\n/**\n * Returns a filtered `process.argv` with only options and their values.\n * \n * @param {string} Args - A value of `process.argv`.\n * @returns A filtered `process.argv` with only options and their values.\n */\nexport function PreProcessing<Args extends typeof Process.argv>(Args: Args): DropFirstANDTwo<Args> | DropFirst<Args> {\n  if (Args[2].startsWith('--')) {\n    return Args.slice(2) as DropFirstANDTwo<Args>\n  } else {\n    return Args.slice(1) as DropFirst<Args>\n  }\n}"],
+  "mappings": ";AAAA,SAAS,WAAW,KAAK;AACrB,SAAQ,IAAI,OAAO,CAAC,EAAE,YAAY,IAAI,IAAI,MAAM,CAAC,EAAE,YAAY;AACnE;;;ACFA,IAAM,qBAAqB;AAC3B,SAAS,MAAM,KAAK;AAChB,SAAO,MAAM,KAAK,IAAI,MAAM,kBAAkB,KAAK,CAAC,CAAC;AACzD;;;ACAA,SAAS,WAAW,KAAK;AACrB,QAAM,UAAU,MAAM,GAAG;AACzB,SAAO,QAAQ,IAAI,UAAQ,WAAW,IAAI,CAAC,EAAE,KAAK,EAAE;AACxD;;;ACKA,eAAsB,eAAoC,MAAgB,cAA+B;AAAA,EACvG,kBAA4B;AAC9B,GAAkD;AAChD,QAAM,UAA4C,uBAAO,OAAO,IAAI;AACpE,QAAM,aAAuB,CAAC;AAE9B,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,QAAI,KAAK,CAAC,MAAM,MAAM;AACpB,iBAAW,KAAK,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AACpC;AAAA,IACF;AAEA,QAAI,KAAK,CAAC,EAAE,WAAW,IAAI,GAAG;AAC5B,UAAI,IAAI,MAAM,KAAK,UAAU,KAAK,IAAI,CAAC,EAAE,WAAW,IAAI,GAAG;AACzD,gBAAQ,MAAM,YAAY,iBAAiB,KAAK,CAAC,CAAC,CAAC,IAAI;AAAA,MACzD,OAAO;AACL,gBAAQ,MAAM,YAAY,iBAAiB,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;AACjE;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAuB,WAAW;AAC7C;;;ACvBO,SAAS,cAAgD,MAAqD;AACnH,MAAI,KAAK,CAAC,EAAE,WAAW,IAAI,GAAG;AAC5B,WAAO,KAAK,MAAM,CAAC;AAAA,EACrB,OAAO;AACL,WAAO,KAAK,MAAM,CAAC;AAAA,EACrB;AACF;",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typescriptprime/parsing",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "scripts": {
     "build:esbuild": "esbuild sources/index.ts --bundle --format=esm --splitting --sourcemap --target=es2024 --external:/node_modules --outdir=dist",
     "build:tsc": "tsc sources/index.ts --outDir dist/types --declaration --emitDeclarationOnly",