@clerc/advanced-types 0.0.1 → 1.0.0-beta.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Ray <https://github.com/so1ve>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,26 @@
 # @clerc/advanced-types
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![NPM version](https://img.shields.io/npm/v/@clerc/advanced-types?color=a1b858&label=)](https://www.npmjs.com/package/@clerc/advanced-types)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Advanced runtime types for Clerc.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Exports additional types that can be used to validate and parse data at runtime, extending the capabilities of the core Clerc library.
 
-## Purpose
+> [!NOTE]  
+> You don't have to install this package separately if you are already using `@clerc/core` package as it has re-exported all the types from this package.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@clerc/advanced-types`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## 📦 Installation
 
-## What is OIDC Trusted Publishing?
+```bash
+$ npm install @clerc/advanced-types
+$ yarn add @clerc/advanced-types
+$ pnpm add @clerc/advanced-types
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## 🚀 Usage
 
-## Setup Instructions
+Please refer to [src/index.ts](src/index.ts).
 
-To properly configure OIDC trusted publishing for this package:
+## 📝 License
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+[MIT](../../LICENSE). Made with ❤️ by [Ray](https://github.com/so1ve)

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+//#region ../parser/src/types.d.ts
+
+/**
+* Defines how a string input is converted to the target type T.
+*
+* @template T The target type.
+*/
+interface TypeFunction<T = unknown> {
+  (value: string): T;
+  /**
+  * Optional display name for the type, useful in help output.
+  * If provided, this will be shown instead of the function name.
+  */
+  display?: string;
+}
+//#endregion
+//#region src/errors.d.ts
+declare class FlagValidationError extends Error {}
+//#endregion
+//#region src/index.d.ts
+/**
+* Creates a Enum type function that validates the input against allowed values.
+* The display name will be formatted as "value1 | value2 | ..." for help output.
+*
+* @param values - Array of allowed string values
+* @returns A TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
+*
+* @example
+* ```typescript
+* const format = Enum(['json', 'yaml', 'xml']);
+* // Help output will show: json | yaml | xml
+* ```
+*/
+declare function Enum<T extends string>(...values: T[]): TypeFunction<T>;
+/**
+* Creates a range type function that validates the input is a number within the specified range.
+*
+* @param min - The minimum acceptable value (inclusive)
+* @param max - The maximum acceptable value (inclusive)
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value is not a number or is outside the specified range
+*/
+declare function Range(min: number, max: number): TypeFunction<number>;
+/**
+* Creates a regex type function that validates the input against the provided pattern.
+*
+* @param pattern - The regular expression pattern to validate against
+* @param description - Optional description for display purposes
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value does not match the regex pattern
+*/
+declare function Regex(pattern: RegExp, description?: string): TypeFunction<string>;
+//#endregion
+export { Enum, FlagValidationError, Range, Regex };

package/dist/index.js

@@ -0,0 +1,63 @@
+//#region src/errors.ts
+var FlagValidationError = class extends Error {};
+
+//#endregion
+//#region src/index.ts
+/**
+* Creates a Enum type function that validates the input against allowed values.
+* The display name will be formatted as "value1 | value2 | ..." for help output.
+*
+* @param values - Array of allowed string values
+* @returns A TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
+*
+* @example
+* ```typescript
+* const format = Enum(['json', 'yaml', 'xml']);
+* // Help output will show: json | yaml | xml
+* ```
+*/
+function Enum(...values) {
+	const fn = ((value) => {
+		if (!values.includes(value)) throw new FlagValidationError(`Invalid value: ${value}. Must be one of: ${values.join(", ")}`);
+		return value;
+	});
+	fn.display = values.join(" | ");
+	return fn;
+}
+/**
+* Creates a range type function that validates the input is a number within the specified range.
+*
+* @param min - The minimum acceptable value (inclusive)
+* @param max - The maximum acceptable value (inclusive)
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value is not a number or is outside the specified range
+*/
+function Range(min, max) {
+	const fn = ((value) => {
+		const num = Number(value);
+		if (Number.isNaN(num) || num < min || num > max) throw new FlagValidationError(`Invalid value: ${value}. Must be a number between ${min} and ${max}`);
+		return num;
+	});
+	fn.display = `${min} - ${max}`;
+	return fn;
+}
+/**
+* Creates a regex type function that validates the input against the provided pattern.
+*
+* @param pattern - The regular expression pattern to validate against
+* @param description - Optional description for display purposes
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value does not match the regex pattern
+*/
+function Regex(pattern, description) {
+	const fn = ((value) => {
+		if (!pattern.test(value)) throw new FlagValidationError(`Invalid value: ${value}. Must match pattern: ${pattern}`);
+		return value;
+	});
+	fn.display = description ?? `Regex: ${pattern.toString()}`;
+	return fn;
+}
+
+//#endregion
+export { Enum, FlagValidationError, Range, Regex };

package/package.json

@@ -1,10 +1,45 @@
 {
   "name": "@clerc/advanced-types",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @clerc/advanced-types",
+  "version": "1.0.0-beta.29",
+  "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
+  "type": "module",
+  "description": "Clerc advanced types",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "args",
+    "arguments",
+    "argv",
+    "clerc",
+    "cli"
+  ],
+  "homepage": "https://github.com/clercjs/clerc/tree/main/packages/advanced-types#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clercjs/clerc.git",
+    "directory": "/"
+  },
+  "bugs": {
+    "url": "https://github.com/clercjs/clerc/issues"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}