cleye 2.5.0 → 2.6.0

package/README.md

@@ -342,6 +342,36 @@ const argv = cli({
 argv.flags.size // => "large" ("small" | "medium" | "large")
 ```
 
+#### Composable type helpers
+
+`cleye/formats` is a tree-shakable subpath that ships ready-made type-function helpers for common flag shapes. Import only what you need.
+
+```ts
+import {
+    oneOf, commaList, integer, float, range, url
+} from 'cleye/formats'
+
+cli({
+    flags: {
+        format: { type: oneOf('json', 'yaml', 'csv') }, // => 'json' | 'yaml' | 'csv'
+        tags: { type: commaList(String) }, // => string[]
+        port: { type: range(1024, 65_535) }, // => number, validated in range
+        count: { type: integer() }, // => number (integer only)
+        ratio: { type: float() }, // => number (finite float)
+        apiUrl: { type: url() } // => URL object
+    }
+})
+```
+
+| Helper | Return type | Description |
+|--------|-------------|-------------|
+| `oneOf(...values)` | Union of the given string literals | Throws if the value is not in the list. |
+| `commaList(itemType)` | `T[]` | Splits on `,`, trims whitespace, maps each item through `itemType`. |
+| `integer()` | `number` | Parses a base-10 integer. Throws on floats or non-numeric input. |
+| `float()` | `number` | Parses a finite float. Throws on non-finite or non-numeric input. |
+| `range(min, max)` | `(input: string) => number` | Returns a parser that validates the input parses to a number in `[min, max]`. |
+| `url()` | `URL` | Parses with `new URL()`. Returns a `URL` object so callers get `.host`, `.pathname`, etc. |
+
 #### Default flags
 By default, _Cleye_ will try to handle the `--help, -h` and `--version` flags.
 
@@ -366,6 +396,18 @@ $ my-script --version
 
 The version is also shown in the help documentation. To opt out of handling `--version` while still showing the version in `--help`, pass the version into `help.version`.
 
+> [!TIP]
+> Import `name`, `version`, and `description` directly from `package.json` to avoid keeping them in sync manually:
+> ```ts
+> import { name, version, description } from './package.json' with { type: 'json' }
+>
+> cli({
+>     name,
+>     version,
+>     help: { description }
+> })
+> ```
+
 #### Strict flags
 To reject unknown flags with an error, enable `strictFlags`:
 

package/dist/formats.cjs

@@ -0,0 +1 @@
+"use strict";var i=Object.defineProperty;var n=(r,e)=>i(r,"name",{value:e,configurable:!0});const s=n((...r)=>e=>{if(!r.includes(e))throw new Error(`Expected one of: ${r.join(", ")} (got: ${JSON.stringify(e)})`);return e},"oneOf"),c=n(r=>e=>e===""?[]:e.split(",").flatMap(o=>{const t=o.trim();return t===""?[]:[r(t)]}),"commaList"),f=n(()=>r=>{const e=Number(r);if(!Number.isInteger(e))throw new TypeError(`Expected an integer (got: ${JSON.stringify(r)})`);return e},"integer"),a=n(()=>r=>{const e=Number(r);if(!Number.isFinite(e))throw new TypeError(`Expected a finite number (got: ${JSON.stringify(r)})`);return e},"float"),g=n((r,e)=>o=>{const t=Number(o);if(!Number.isFinite(t))throw new TypeError(`Expected a number (got: ${JSON.stringify(o)})`);if(t<r||t>e)throw new Error(`Expected a number between ${r} and ${e} (got: ${t})`);return t},"range"),u=n(()=>r=>{try{return new URL(r)}catch{throw new Error(`Expected a valid URL (got: ${JSON.stringify(r)})`)}},"url");exports.commaList=c,exports.float=a,exports.integer=f,exports.oneOf=s,exports.range=g,exports.url=u;

package/dist/formats.d.cts

@@ -0,0 +1,8 @@
+declare const oneOf: <T extends string>(...values: T[]) => (input: string) => T;
+declare const commaList: <T>(itemType: (value: string) => T) => (input: string) => T[];
+declare const integer: () => (input: string) => number;
+declare const float: () => (input: string) => number;
+declare const range: (min: number, max: number) => (input: string) => number;
+declare const url: () => (input: string) => URL;
+
+export { commaList, float, integer, oneOf, range, url };

package/dist/formats.d.mts

@@ -0,0 +1,8 @@
+declare const oneOf: <T extends string>(...values: T[]) => (input: string) => T;
+declare const commaList: <T>(itemType: (value: string) => T) => (input: string) => T[];
+declare const integer: () => (input: string) => number;
+declare const float: () => (input: string) => number;
+declare const range: (min: number, max: number) => (input: string) => number;
+declare const url: () => (input: string) => URL;
+
+export { commaList, float, integer, oneOf, range, url };

package/dist/formats.mjs

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(r,e)=>i(r,"name",{value:e,configurable:!0});const c=n((...r)=>e=>{if(!r.includes(e))throw new Error(`Expected one of: ${r.join(", ")} (got: ${JSON.stringify(e)})`);return e},"oneOf"),s=n(r=>e=>e===""?[]:e.split(",").flatMap(o=>{const t=o.trim();return t===""?[]:[r(t)]}),"commaList"),f=n(()=>r=>{const e=Number(r);if(!Number.isInteger(e))throw new TypeError(`Expected an integer (got: ${JSON.stringify(r)})`);return e},"integer"),g=n(()=>r=>{const e=Number(r);if(!Number.isFinite(e))throw new TypeError(`Expected a finite number (got: ${JSON.stringify(r)})`);return e},"float"),a=n((r,e)=>o=>{const t=Number(o);if(!Number.isFinite(t))throw new TypeError(`Expected a number (got: ${JSON.stringify(o)})`);if(t<r||t>e)throw new Error(`Expected a number between ${r} and ${e} (got: ${t})`);return t},"range"),u=n(()=>r=>{try{return new URL(r)}catch{throw new Error(`Expected a valid URL (got: ${JSON.stringify(r)})`)}},"url");export{s as commaList,g as float,f as integer,c as oneOf,a as range,u as url};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleye",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "The intuitive CLI development tool",
   "keywords": [
     "cli",
@@ -23,17 +23,30 @@
     "skills"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "exports": {
-    "require": {
-      "types": "./dist/index.d.cts",
-      "default": "./dist/index.cjs"
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
     },
-    "import": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
+    "./formats": {
+      "require": {
+        "types": "./dist/formats.d.cts",
+        "default": "./dist/formats.cjs"
+      },
+      "import": {
+        "types": "./dist/formats.d.mts",
+        "default": "./dist/formats.mjs"
+      }
     }
   },
   "imports": {
@@ -41,6 +54,11 @@
       "types": "./src/index.ts",
       "development": "./src/index.ts",
       "default": "./dist/index.mjs"
+    },
+    "#cleye/formats": {
+      "types": "./src/formats.ts",
+      "development": "./src/formats.ts",
+      "default": "./dist/formats.mjs"
     }
   },
   "dependencies": {

package/skills/cleye/SKILL.md

@@ -172,6 +172,18 @@ cli({
 // help: false  — disables --help handling; call argv.showHelp() manually
 ```
 
+Tip: import `name`, `version`, and `description` from `package.json` to avoid keeping them in sync manually:
+
+```ts
+import { name, version, description } from './package.json' with { type: 'json' }
+
+cli({
+    name,
+    version,
+    help: { description }
+})
+```
+
 ## Custom Flag Types
 
 Any function `(value: string) => T` works as a flag type — the return type is inferred.
@@ -210,6 +222,23 @@ cli({ flags: { env: [Env] } })
 // --env.TOKEN=abc --env.CI → merge to { TOKEN: 'abc', CI: true }
 ```
 
+## Type Helpers (`cleye/formats`)
+
+`cleye/formats` ships composable, tree-shakable type-function helpers. Import only what you need.
+
+```ts
+import {
+    oneOf, commaList, integer, float, range, url
+} from 'cleye/formats'
+```
+
+- `oneOf('a', 'b', 'c')` — infers `'a' | 'b' | 'c'`; throws if the value is not in the list.
+- `commaList(itemType)` — splits `"a,b,c"` → `T[]`; trims whitespace; composes with other helpers (e.g. `commaList(integer())`).
+- `integer()` — base-10 integer; throws on floats/non-numeric.
+- `float()` — finite float; throws on `Infinity`/non-numeric.
+- `range(min, max)` — returns `(input: string) => number`; validates input parses to a number in `[min, max]`.
+- `url()` — parses with `new URL()`; returns a `URL` object (not a string).
+
 ## Help Customization
 
 ```ts