npm package: @marcuth/argus
Description: **@marcuth/argus** is a simple and strongly typed command parser built with [Zod](https://zod.dev) for argument validation. It allows you to easily define command prefixes, extract arguments, and validate them against strict schemas.
Author: Marcuth
Latest version: 0.1.0

# @marcuth/argus

**@marcuth/argus** is a simple and strongly typed command parser built with [Zod](https://zod.dev) for argument validation. It allows you to easily define command prefixes, extract arguments, and validate them against strict schemas.

## 📦 Installation

Installation is straightforward; simply use your preferred package manager. You also need to install `zod` as a peer dependency. Here is an example using NPM:

```bash
npm i @marcuth/argus zod
```

## 🚀 Usage

<a href="https://www.buymeacoffee.com/marcuth">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="200">
</a>

### Initialization

To start, create an instance of the `Argus` class and define the prefix for your commands.

```typescript
import { Argus, ArgusError } from "@marcuth/argus"
import { z } from "zod"

const argus = new Argus({
    prefix: "!",
    // argumentSeparator: " " // Optional, defaults to space
})
```

### Handling Commands

You can verify if a string is a command, extract its raw arguments, and then validate them using a `Zod` schema. Arguments are positional and map directly to the keys in your schema.

```typescript
const text = "!hello world 25"

if (argus.isCommand(text)) {
    try {
        // 1. Extract command name and raw arguments
        const props = argus.extractCommandProps(text)
        
        console.log(`Command: ${props.name}`) // "hello"

        // 2. Define the validation schema
        // Arguments are mapped positionally to these keys
        const optionsSchema = z.object({
            name: z.string(),
            age: z.coerce.number(), // Coerce string to number
            email: z.string().email().optional() // Optional argument
        })

        // 3. Validate and parse the arguments
        const validated = argus.validateCommandWithArguments({
            name: props.name,
            arguments: props.arguments,
            schema: optionsSchema
        })

        console.log("Validated Options:", validated.options)
        // Output: { name: "world", age: 25 }

    } catch (error) {
        if (error instanceof ArgusError) {
            console.error("Command Error:", error.message)
        } else if (error instanceof z.ZodError) {
            console.error("Validation Error:", error.errors)
        }
    }
}
```

---

## ⚙️ Features

- **Custom Prefix**: Define any character or string as your command prefix.
- **Zod Powered**: Leverage the full power of Zod for validation and transformation (e.g., `z.coerce.number()`).
- **Positional Mapping**: Arguments from the input string are mapped sequentially to your Zod schema keys.
- **Optional Arguments**: Support for optional fields at the end of your argument list.

## ⚠️ Error Handling

`Argus` throws specific errors that you can catch:

*   `ArgusError`: Thrown when there's an issue with the arguments count (too many or too few).
*   `ZodError`: Thrown when argument validation fails against the provided schema (e.g., passing text where a number is expected).

## 🧪 Testing

Automated tests are located in the `__tests__` directory. To run them:

```bash
npm run test
```

## 🤝 Contributing

Want to contribute? Follow these steps:

1. Fork the repository.
2. Create a new branch (`git checkout -b feature-new`).
3. Commit your changes (`git commit -m 'Add new feature'`).
4. Push to the branch (`git push origin feature-new`).
5. Open a Pull Request.

## 📝 License

This project is licensed under the MIT License.