@marcuth/argus

@marcuth/argus is a simple and strongly typed command parser built with Zod 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:

npm i @marcuth/argus zod

🚀 Usage

Initialization

To start, create an instance of the Argus class and define the prefix for your commands.

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.

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:

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.