update docs

Author: sigmaSd

README.md

@@ -66,7 +66,7 @@ Subcommands are plain classes (no need to extend `Args`). Link them using
 `@subCommand`:
 
 ```typescript
-import { Args, cli, opt, subCommand } from "@sigma/parse";
+import { Args, cli, command, opt, subCommand } from "@sigma/parse";
 
 @command
 class ServeCommand {
@@ -122,14 +122,14 @@ if (args.serve) {
 
 **Explicitly Required** (must be provided on CLI):
 
-```typescript
+```typescript ignore
 @opt({ type: "string", required: true })
 apiKey!: string;
 ```
 
 **Optional with Default** (inferred from value):
 
-```typescript
+```typescript ignore
 port = 8080; // type inferred as number
 ```
 
@@ -138,7 +138,7 @@ port = 8080; // type inferred as number
 Use `short: true` to automatically use the first character of the property name
 as a short flag:
 
-```typescript
+```typescript ignore
 verbose = false; // becomes -v, --verbose
 ```
 
@@ -147,20 +147,20 @@ verbose = false; // becomes -v, --verbose
 ### Built-in Validators
 
 ```typescript
-import { Args, cli, opt, pattern, range } from "@sigma/parse";
+import { Args, cli, oneOf, opt, pattern, range, validate } from "@sigma/parse";
 
 @cli({ name: "example" })
 class Example extends Args {
   @opt()
-  @range(1, 100)
+  @validate(range(1, 100))
   score = 50;
 
   @opt()
-  @oneOf(["dev", "prod"])
+  @validate(oneOf(["dev", "prod"]))
   env = "dev";
 
   @opt()
-  @pattern(/^[a-z]+$/)
+  @validate(pattern(/^[a-z]+$/))
   user = "admin";
 }
 ```
@@ -169,7 +169,7 @@ class Example extends Args {
 
 Use `raw: true` to build wrappers that forward arguments to other tools:
 
-```typescript
+```typescript ignore
 @cli({ name: "proxy" })
 class Proxy extends Args {
   @arg({ description: "Command to run", required: true })

src/decorators.ts

@@ -69,25 +69,44 @@ export function addValidator(validator: Validator): (
 /**
  * Validate decorator for custom validation logic.
  *
- * This decorator creates a validator using a predicate function and custom error message.
+ * This decorator can be used in two ways:
+ * 1. With a built-in or custom validator function (e.g., `@validate(range(1, 10))`)
+ * 2. With a predicate function and custom error message (e.g., `@validate(val => val > 0, "must be positive")`)
  *
- * @param predicate - Function that returns true if value is valid
- * @param message - Error message to show when validation fails
+ * @param validatorOrPredicate - A validator function OR a predicate function
+ * @param message - Error message (required only if using a predicate)
  * @returns A decorator function
  */
+export function validate<T>(
+  validator: Validator,
+): (
+  _target: unknown,
+  context: DecoratorContext,
+) => void;
 export function validate<T>(
   predicate: (value: T) => boolean,
   message: string,
 ): (
   _target: unknown,
   context: DecoratorContext,
+) => void;
+export function validate<T>(
+  validatorOrPredicate: Validator | ((value: T) => boolean),
+  message?: string,
+): (
+  _target: unknown,
+  context: DecoratorContext,
 ) => void {
-  return addValidator((value: unknown) => {
-    if (!predicate(value as T)) {
-      return message;
+  const validator = typeof message === "string"
+    ? (value: unknown) => {
+      if (!(validatorOrPredicate as (value: T) => boolean)(value as T)) {
+        return message;
+      }
+      return null;
     }
-    return null;
-  });
+    : (validatorOrPredicate as Validator);
+
+  return addValidator(validator);
 }
 
 /**
@@ -176,7 +195,7 @@ export function subCommand<T extends new () => unknown>(
  * @returns A decorator function
  *
  * @example
- * ```ts
+ * ```ts ignore
  * class MyArgs extends Args {
  *   @opt({ short: "p", description: "Port", required: true })
  *   port!: number;
@@ -244,7 +263,7 @@ export function opt(
  * @returns A decorator function
  *
  * @example
- * ```ts
+ * ```ts ignore
  * class MyArgs extends Args {
  *   @arg({ description: "Input file", required: true })
  *   input!: string;

src/validation.ts

@@ -92,12 +92,12 @@ export function requiredValidator(): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, min } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("number")
- *   @addValidator(min(0))
+ *   @opt({ type: "number" })
+ *   @validate(min(1024))
  *   port = 3000;
  * }
  * ```
@@ -119,12 +119,12 @@ export function min(minValue: number): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, max } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("number")
- *   @addValidator(max(65535))
+ *   @opt({ type: "number" })
+ *   @validate(max(65535))
  *   port = 3000;
  * }
  * ```
@@ -147,14 +147,13 @@ export function max(maxValue: number): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, required, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, length } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("string")
- *   @required()
- *   @addValidator(length(3, 20))
- *   username?: string;
+ *   @opt({ type: "string" })
+ *   @validate(length(3, 20))
+ *   username = "admin";
  * }
  * ```
  */
@@ -181,14 +180,13 @@ export function length(minLength: number, maxLength?: number): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, required, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, pattern } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("string")
- *   @required()
- *   @addValidator(pattern(/^[a-zA-Z0-9]+$/, "must contain only letters and numbers"))
- *   identifier?: string;
+ *   @opt({ type: "string" })
+ *   @validate(pattern(/^[a-z0-9]+$/))
+ *   slug = "my-post";
  * }
  * ```
  */
@@ -209,11 +207,12 @@ export function pattern(pattern: RegExp, message?: string): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, oneOf } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @addValidator(oneOf(["development", "staging", "production"]))
+ *   @opt()
+ *   @validate(oneOf(["development", "staging", "production"]))
  *   environment = "development";
  * }
  * ```
@@ -236,13 +235,13 @@ export function oneOf<T>(allowedValues: T[]): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, arrayLength } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("string[]")
- *   @addValidator(arrayLength(1, 5))
- *   tags: string[] = [];
+ *   @opt({ type: "string[]" })
+ *   @validate(arrayLength(1, 5))
+ *   tags: string[] = ["typescript"];
  * }
  * ```
  */
@@ -269,14 +268,13 @@ export function arrayLength(minItems: number, maxItems?: number): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, required, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, range } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("number")
- *   @required()
- *   @addValidator(range(1, 100))
- *   percentage?: number;
+ *   @opt({ type: "number" })
+ *   @validate(range(0, 100))
+ *   percentage = 50;
  * }
  * ```
  */
@@ -298,14 +296,13 @@ export function range(minValue: number, maxValue: number): Validator {
  *
  * @example
  * ```ts
- * import { Args, cli, type, required, addValidator } from "@sigma/parse";
+ * import { Args, cli, opt, validate, integer } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("number")
- *   @required()
- *   @addValidator(integer())
- *   count?: number;
+ *   @opt({ type: "number" })
+ *   @validate(integer())
+ *   count = 1;
  * }
  * ```
  */
@@ -326,15 +323,14 @@ export function integer(): Validator {
  * @returns A validator function
  *
  * @example
- * ```ts ignore
- * import { Args, cli, type, required, addValidator } from "@sigma/parse";
+ * ```ts
+ * import { Args, cli, opt, validate, custom } from "@sigma/parse";
  *
  * @cli({ name: "example" })
  * class Config extends Args {
- *   @type("number")
- *   @required()
- *   @addValidator(custom((n: number) => n % 2 === 0, "must be even"))
- *   evenNumber?: number;
+ *   @opt({ type: "number" })
+ *   @validate(custom((n: number) => n % 2 === 0, "must be even"))
+ *   evenNumber = 2;
  * }
  * ```
  */