@vyriy/script 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy contributors
+
+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

@@ -0,0 +1,136 @@
+# @vyriy/script
+
+Composable script wrappers for Vyriy projects.
+
+## Purpose
+
+This package provides a small composition layer for CLI-style or bootstrap-style async tasks.
+
+It includes:
+
+- a generic `factory()` helper for building wrappers
+- `compose()` for combining decorators
+- a ready-made `script` decorator with the default Vyriy wrapper chain
+- focused wrappers for error handling, logging, timeout control, and process exit codes
+
+## Install
+
+With npm:
+
+```bash
+npm install @vyriy/script
+```
+
+With Yarn:
+
+```bash
+yarn add @vyriy/script
+```
+
+## Usage
+
+Use the default `script` decorator:
+
+```ts
+import { script } from '@vyriy/script';
+
+await script(async () => {
+  // your task
+});
+```
+
+Or compose wrappers manually:
+
+```ts
+import { compose, withError, withLogger, withTimeout } from '@vyriy/script';
+
+const run = compose(
+  withError({
+    errorHandler: async (error) => {
+      console.error('Task failed:', error);
+    },
+  }),
+  withLogger(),
+  withTimeout(),
+);
+
+await run(async () => {
+  // your task
+});
+```
+
+## Default Script Chain
+
+The exported `script` decorator is built from:
+
+- `withExit()`
+- `withError()`
+- `withLogger()`
+- `withTimeout()`
+
+Applied through `compose(...)`, this means the task gets timeout handling, logging, error interception, and final process exit handling in one reusable decorator.
+
+## API
+
+- `compose(...decorators)`
+  Combines decorators from right to left into one decorator.
+
+- `factory(wrapper)`
+  Creates decorator factories from `(task, options?) => Promise<void>` wrappers.
+
+- `script`
+  Default decorator composed from the built-in wrappers.
+
+- `withError(options?)`
+  Wraps a task with optional async error handling.
+
+- `withExit()`
+  Exits the process with `0` on success and `1` on failure.
+
+- `withLogger(options?)`
+  Logs task start, success, and failure messages. Uses `createLogger()` by default.
+
+- `withTimeout()`
+  Reads `TIMEOUT` through `@vyriy/config` and races the task against `@vyriy/timeout`.
+
+## Wrapper Options
+
+`withError(options?)`
+
+```ts
+{
+  errorHandler?: (error: unknown) => Promise<void>;
+}
+```
+
+`withLogger(options?)`
+
+```ts
+{
+  logger?: typeof console;
+}
+```
+
+## Exports
+
+The package exposes:
+
+```ts
+import { compose, factory, script, withError, withExit, withLogger, withTimeout } from '@vyriy/script';
+
+import { compose } from '@vyriy/script/compose';
+import { factory } from '@vyriy/script/factory';
+
+import { withError } from '@vyriy/script/wrapper/error';
+import { withExit } from '@vyriy/script/wrapper/exit';
+import { withLogger } from '@vyriy/script/wrapper/logger';
+import { withTimeout } from '@vyriy/script/wrapper/timeout';
+
+import type { Compose, Decorator, Factory, Result, Task, Wrapper } from '@vyriy/script/types';
+```
+
+## Notes
+
+- decorators operate on async tasks shaped as `() => Promise<void>`
+- `withTimeout()` uses no timeout when `TIMEOUT` is missing and parses configured values as durations
+- `withExit()` is intended for real script entrypoints because it calls `process.exit(...)`

package/compose.d.ts

@@ -0,0 +1,2 @@
+import type { Compose } from './types.js';
+export declare const compose: Compose;

package/compose.js

@@ -0,0 +1,3 @@
+export const compose = (...fns) => fns.length
+    ? fns.reduceRight((prevFn, nextFn) => async (task) => nextFn(async () => prevFn(task)))
+    : async (task) => task();

package/factory.d.ts

@@ -0,0 +1,2 @@
+import type { Decorator, Wrapper } from './types.js';
+export declare const factory: <O = void>(wrapper: Wrapper<O>) => (options?: O) => Decorator;

package/factory.js

@@ -0,0 +1 @@
+export const factory = (wrapper) => (options) => (task) => wrapper(task, options);

package/index.d.ts

@@ -0,0 +1,8 @@
+export * from './script.js';
+export * from './compose.js';
+export * from './factory.js';
+export * from './wrapper/error.js';
+export * from './wrapper/exit.js';
+export * from './wrapper/logger.js';
+export * from './wrapper/timeout.js';
+export type * from './types.js';

package/index.js

@@ -0,0 +1,7 @@
+export * from './script.js';
+export * from './compose.js';
+export * from './factory.js';
+export * from './wrapper/error.js';
+export * from './wrapper/exit.js';
+export * from './wrapper/logger.js';
+export * from './wrapper/timeout.js';

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@vyriy/script",
+  "version": "0.1.9",
+  "description": "Script utilities for Vyriy projects",
+  "type": "module",
+  "main": "./index.js",
+  "dependencies": {
+    "@vyriy/config": "0.1.9",
+    "@vyriy/logger": "0.1.9",
+    "@vyriy/timeout": "0.1.9"
+  },
+  "license": "MIT",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./compose": {
+      "types": "./compose.d.ts",
+      "import": "./compose.js",
+      "default": "./compose.js"
+    },
+    "./compose.js": {
+      "types": "./compose.d.ts",
+      "import": "./compose.js",
+      "default": "./compose.js"
+    },
+    "./factory": {
+      "types": "./factory.d.ts",
+      "import": "./factory.js",
+      "default": "./factory.js"
+    },
+    "./factory.js": {
+      "types": "./factory.d.ts",
+      "import": "./factory.js",
+      "default": "./factory.js"
+    },
+    "./index": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index.js": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./script": {
+      "types": "./script.d.ts",
+      "import": "./script.js",
+      "default": "./script.js"
+    },
+    "./script.js": {
+      "types": "./script.d.ts",
+      "import": "./script.js",
+      "default": "./script.js"
+    },
+    "./wrapper/error": {
+      "types": "./wrapper/error.d.ts",
+      "import": "./wrapper/error.js",
+      "default": "./wrapper/error.js"
+    },
+    "./wrapper/error.js": {
+      "types": "./wrapper/error.d.ts",
+      "import": "./wrapper/error.js",
+      "default": "./wrapper/error.js"
+    },
+    "./wrapper/exit": {
+      "types": "./wrapper/exit.d.ts",
+      "import": "./wrapper/exit.js",
+      "default": "./wrapper/exit.js"
+    },
+    "./wrapper/exit.js": {
+      "types": "./wrapper/exit.d.ts",
+      "import": "./wrapper/exit.js",
+      "default": "./wrapper/exit.js"
+    },
+    "./wrapper/logger": {
+      "types": "./wrapper/logger.d.ts",
+      "import": "./wrapper/logger.js",
+      "default": "./wrapper/logger.js"
+    },
+    "./wrapper/logger.js": {
+      "types": "./wrapper/logger.d.ts",
+      "import": "./wrapper/logger.js",
+      "default": "./wrapper/logger.js"
+    },
+    "./wrapper/timeout": {
+      "types": "./wrapper/timeout.d.ts",
+      "import": "./wrapper/timeout.js",
+      "default": "./wrapper/timeout.js"
+    },
+    "./wrapper/timeout.js": {
+      "types": "./wrapper/timeout.d.ts",
+      "import": "./wrapper/timeout.js",
+      "default": "./wrapper/timeout.js"
+    }
+  }
+}

package/script.d.ts

@@ -0,0 +1 @@
+export declare const script: import("./types.js").Decorator;

package/script.js

@@ -0,0 +1,6 @@
+import { withExit } from './wrapper/exit.js';
+import { withError } from './wrapper/error.js';
+import { withLogger } from './wrapper/logger.js';
+import { withTimeout } from './wrapper/timeout.js';
+import { compose } from './compose.js';
+export const script = compose(withExit(), withError(), withLogger(), withTimeout());

package/types.d.ts

@@ -0,0 +1,6 @@
+export type Result = Promise<void>;
+export type Task = () => Result;
+export type Wrapper<O = void> = (task: Task, options?: O) => Result;
+export type Decorator = (task: Task) => Result;
+export type Factory = <O = void>(wrapper: Wrapper<O>) => (options?: O) => Decorator;
+export type Compose = (...decorators: Decorator[]) => Decorator;

package/wrapper/error.d.ts

@@ -0,0 +1,4 @@
+export type ErrorOptions = {
+    errorHandler?: (err: unknown) => Promise<void>;
+};
+export declare const withError: (options?: ErrorOptions | undefined) => import("../types.js").Decorator;

package/wrapper/error.js

@@ -0,0 +1,13 @@
+import { factory } from '../factory.js';
+export const withError = factory(async (handler, options) => {
+    const errorHandler = options?.errorHandler;
+    try {
+        await handler();
+    }
+    catch (error) {
+        if (errorHandler) {
+            await errorHandler(error);
+        }
+        throw error;
+    }
+});

package/wrapper/exit.d.ts

@@ -0,0 +1 @@
+export declare const withExit: (options?: void | undefined) => import("../types.js").Decorator;

package/wrapper/exit.js

@@ -0,0 +1,10 @@
+import { factory } from '../factory.js';
+export const withExit = factory(async (handler) => {
+    try {
+        await handler();
+        process.exit(0);
+    }
+    catch {
+        process.exit(1);
+    }
+});

package/wrapper/logger.d.ts

@@ -0,0 +1,4 @@
+export type LoggerOptions = {
+    logger?: typeof console;
+};
+export declare const withLogger: (options?: LoggerOptions | undefined) => import("../types.js").Decorator;

package/wrapper/logger.js

@@ -0,0 +1,17 @@
+import { createLogger } from '@vyriy/logger';
+import { factory } from '../factory.js';
+export const withLogger = factory(async (handler, options = {}) => {
+    const { logger = createLogger() } = options;
+    logger.info('Task started...');
+    try {
+        await handler();
+        logger.info('Task finished!');
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            logger.error('Task error:', error.message);
+        }
+        logger.error(error);
+        throw error;
+    }
+});

package/wrapper/timeout.d.ts

@@ -0,0 +1 @@
+export declare const withTimeout: (options?: void | undefined) => import("../types.js").Decorator;

package/wrapper/timeout.js

@@ -0,0 +1,12 @@
+import { getConfig, Parser } from '@vyriy/config';
+import { timeout as error } from '@vyriy/timeout';
+import { factory } from '../factory.js';
+export const withTimeout = factory(async (handler) => {
+    const timeout = getConfig('TIMEOUT', 0, Parser.duration);
+    if (timeout) {
+        await Promise.race([handler(), error(timeout)]);
+    }
+    else {
+        await handler();
+    }
+});