@venizia/ignis-docs 0.0.1-1

package/wiki/references/utilities/crypto.md

@@ -0,0 +1,39 @@
+# Crypto Utility
+
+The Crypto utility provides simple, stateless functions for cryptographic hashing.
+
+## `hash`
+
+The `hash` function allows you to create a hash of a string using either `SHA256` (with a secret for HMAC) or `MD5`.
+
+### `hash(text, options)`
+
+-   `text` (string): The input string to hash.
+-   `options` (object):
+    -   `algorithm` ('SHA256' | 'MD5'): The hashing algorithm to use.
+    -   `secret` (string, optional): The secret key for HMAC-SHA256.
+    -   `outputType` (BinaryToTextEncoding): The output encoding (e.g., 'hex', 'base64').
+
+### Examples
+
+**MD5 Hash**
+
+```typescript
+import { hash } from '@venizia/ignis';
+
+const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });
+// => '552e21cd4cd99186789c2370c7482837'
+```
+
+**SHA256 HMAC**
+
+```typescript
+import { hash } from '@venizia/ignis';
+
+const sha256Hash = hash('some text', {
+  algorithm: 'SHA256',
+  secret: 'a-secret-key',
+  outputType: 'hex',
+});
+// => 'b8a1c3f2... (64-character hex string)'
+```

package/wiki/references/utilities/date.md

@@ -0,0 +1,72 @@
+# Date Utility
+
+The Date utility provides a set of functions for date and time manipulation, built on top of the powerful `dayjs` library. It also configures `dayjs` with useful plugins and a default timezone.
+
+## `dayjs`
+
+The `dayjs` object is re-exported, so you can use it directly for any date and time operations. It is pre-configured with the following plugins: `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, and `IsoWeek`.
+
+```typescript
+import { dayjs } from '@venizia/ignis';
+
+// Get the current date and time
+const now = dayjs();
+
+// Format a date
+const formatted = now.format('YYYY-MM-DD HH:mm:ss');
+```
+
+## `sleep`
+
+The `sleep` function pauses execution for a specified number of milliseconds.
+
+```typescript
+import { sleep } from '@venizia/ignis';
+
+async function myAsyncFunction() {
+  console.log('Start');
+  await sleep(2000); // Wait for 2 seconds
+  console.log('End');
+}
+```
+
+## Weekday Functions
+
+-   **`isWeekday(date)`**: Checks if a given date is a weekday (Monday to Friday).
+-   **`getPreviousWeekday(opts)`**: Returns the previous weekday from a given date.
+-   **`getNextWeekday(opts)`**: Returns the next weekday from a given date.
+
+```typescript
+import { isWeekday, getPreviousWeekday } from '@venizia/ignis';
+
+const isTodayWeekday = isWeekday(new Date());
+
+const lastBusinessDay = getPreviousWeekday();
+```
+
+## `getDateTz`
+
+The `getDateTz` function allows you to get a `dayjs` object in a specific timezone, with an optional offset.
+
+```typescript
+import { getDateTz } from '@venizia/ignis';
+
+const tokyoTime = getDateTz({
+  date: '2023-10-27T10:00:00Z',
+  timezone: 'Asia/Tokyo',
+});
+```
+
+## `hrTime`
+
+The `hrTime` function returns a high-resolution time measurement in seconds, useful for performance benchmarking.
+
+```typescript
+import { hrTime } from '@venizia/ignis';
+
+const start = hrTime();
+// ... some long-running operation
+const end = hrTime();
+
+console.log(`Operation took ${end - start} seconds.`);
+```

package/wiki/references/utilities/index.md

@@ -0,0 +1,12 @@
+# Utilities
+
+Utilities are pure, standalone functions that provide common, reusable logic for various tasks within the Ignis framework. They are designed to be simple, stateless, and easy to use.
+
+-   [Crypto](./crypto.md): Simple, stateless cryptographic functions.
+-   [Date](./date.md): Provides date and time manipulation functions, built on `dayjs`.
+-   [Module](./module.md): A utility for checking if a Node.js module is installed.
+-   [Parse](./parse.md): A collection of functions for parsing and converting data types.
+-   [Performance](./performance.md): Utilities for measuring code execution time.
+-   [Promise](./promise.md): Helper functions for working with Promises.
+-   [Request](./request.md): Utilities for handling HTTP requests, such as parsing multipart form data.
+-   [Schema](./schema.md): Helpers for creating and validating Zod schemas, especially for request and response validation in an OpenAPI context.

package/wiki/references/utilities/module.md

@@ -0,0 +1,40 @@
+# Module Utility
+
+The Module utility provides a simple function to validate the existence of a Node.js module at runtime.
+
+## `validateModule`
+
+The `validateModule` function checks if a list of modules can be resolved. If a module is not found, it throws a descriptive error, prompting the developer to install it. This is particularly useful for features that have optional peer dependencies.
+
+### `validateModule(opts)`
+
+-   `opts` (object):
+    -   `scope` (string, optional): A string to identify the feature or component that requires the module, making the error message more informative.
+    -   `modules` (Array<string>): An array of module names to validate.
+
+### Example
+
+The `SwaggerComponent` uses `validateModule` to ensure that `@hono/swagger-ui` is installed before attempting to use it.
+
+```typescript
+import { validateModule } from '@venizia/ignis';
+
+export class SwaggerComponent extends BaseComponent {
+  // ...
+
+  override async binding() {
+    // This will throw an error if '@hono/swagger-ui' is not installed
+    validateModule({ scope: SwaggerComponent.name, modules: ['@hono/swagger-ui'] });
+
+    const { swaggerUI } = await import('@hono/swagger-ui');
+
+    // ... rest of the setup
+  }
+}
+```
+
+If the module is missing, the application will fail to start with an error message like:
+
+```
+[validateModule] @hono/swagger-ui is required for SwaggerComponent. Please install '@hono/swagger-ui'
+```

package/wiki/references/utilities/parse.md

@@ -0,0 +1,68 @@
+# Parse Utility
+
+The Parse utility provides a collection of functions for data type checking, conversion, and transformation.
+
+## Type Checking
+
+-   **`isInt(n)`**: Checks if a value is an integer.
+-   **`isFloat(n)`**: Checks if a value is a float.
+
+## Type Conversion
+
+-   **`int(input)`**: Parses a value to an integer. Handles string with commas and defaults to `0` if the input is invalid.
+-   **`float(input, digit = 2)`**: Parses a value to a float, rounding to a specified number of digits. Handles string with commas and defaults to `0` if the input is invalid.
+-   **`toBoolean(input)`**: Converts various string/number representations (e.g., `'true'`, `'1'`, `1`) to a boolean.
+-   **`toStringDecimal(input, digit = 2)`**: Formats a number to a string with a specified number of decimal places, using locale-specific formatting.
+
+```typescript
+import { int, float, toBoolean } from '@venizia/ignis';
+
+const myInt = int('1,000'); // => 1000
+const myFloat = float('1,234.567', 2); // => 1234.57
+const myBool = toBoolean('true'); // => true
+```
+
+## String and Object Transformation
+
+-   **`toCamel(s)`**: Converts a string from snake_case or kebab-case to camelCase.
+-   **`keysToCamel(object)`**: Recursively converts all keys in an object (and nested objects) to camelCase.
+
+```typescript
+import { toCamel, keysToCamel } from '@venizia/ignis';
+
+const camelString = toCamel('my-snake_case-string');
+// => 'mySnakeCaseString'
+
+const camelObject = keysToCamel({ 'first-name': 'John', 'last_name': 'Doe' });
+// => { firstName: 'John', lastName: 'Doe' }
+```
+
+## Array Transformation
+
+-   **`parseArrayToRecordWithKey(opts)`**: Transforms an array of objects into a record (plain object), using a specified property of the objects as keys.
+-   **`parseArrayToMapWithKey(arr, keyMap)`**: Transforms an array of objects into a `Map`, using a specified property of the objects as keys. This is useful for efficient lookups.
+
+```typescript
+import { parseArrayToMapWithKey } from '@venizia/ignis';
+
+const users = [
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' },
+];
+
+const usersMap = parseArrayToMapWithKey(users, 'id');
+// => Map { 1 => { id: 1, name: 'Alice' }, 2 => { id: 2, name: 'Bob' } }
+
+const user = usersMap.get(1);
+// => { id: 1, name: 'Alice' }
+```
+
+## Unique ID
+
+-   **`getUID()`**: Generates a simple, short unique ID string.
+
+```typescript
+import { getUID } from '@venizia/ignis';
+
+const uniqueId = getUID(); // => e.g., 'A1B2C3D4'
+```

package/wiki/references/utilities/performance.md

@@ -0,0 +1,64 @@
+# Performance Utility
+
+The Performance utility provides functions for measuring and logging the execution time of code blocks, which is useful for identifying bottlenecks and optimizing your application.
+
+## `executeWithPerformanceMeasure`
+
+This is a higher-order function that wraps a task (a function returning a Promise), automatically logging its start time, end time, and total execution duration.
+
+### `executeWithPerformanceMeasure(opts)`
+
+-   `opts` (object):
+    -   `logger` (ApplicationLogger, optional): A logger instance to use for logging. Defaults to `console`.
+    -   `description` (string, optional): A description of the task being measured.
+    -   `scope` (string): A scope to identify the context of the measurement.
+    -   `task` (Function): The asynchronous function (or a function that returns a Promise) to be executed and measured.
+
+### Example
+
+The `BaseApplication` uses this utility to measure the time taken to register components, controllers, and data sources during the startup process.
+
+```typescript
+// Inside BaseApplication class
+import { executeWithPerformanceMeasure } from '@venizia/ignis';
+
+// ...
+
+  async registerComponents() {
+    await executeWithPerformanceMeasure({
+      logger: this.logger,
+      scope: this.registerComponents.name,
+      description: 'Register application components',
+      task: async () => {
+        // ... logic to register components
+      },
+    });
+  }
+```
+
+When `registerComponents` is called, it will produce log output similar to this:
+
+```
+[RegisterComponents] START | Register application components ...
+[RegisterComponents] DONE | Register application components | Took: 12.3456 (ms)
+```
+
+## Low-Level Utilities
+
+For more granular measurements, you can use the lower-level functions:
+
+-   **`getPerformanceCheckpoint()`**: Returns a high-resolution timestamp, which you can use as a starting point.
+-   **`getExecutedPerformance(opts)`**: Calculates the elapsed time in milliseconds since a given checkpoint.
+
+### Example
+
+```typescript
+import { getPerformanceCheckpoint, getExecutedPerformance } from '@venizia/ignis';
+
+const start = getPerformanceCheckpoint();
+
+// ... perform some work
+
+const duration = getExecutedPerformance({ from: start });
+console.log(`The work took ${duration} ms.`);
+```

package/wiki/references/utilities/promise.md

@@ -0,0 +1,83 @@
+# Promise Utility
+
+The Promise utility provides helper functions for working with Promises, particularly for managing concurrency and transforming values.
+
+## `executePromiseWithLimit`
+
+This function executes an array of asynchronous tasks concurrently, but with a specified limit on the number of promises running at any given time. This is useful for throttling asynchronous operations to avoid overwhelming a system (e.g., making a large number of concurrent API calls).
+
+### `executePromiseWithLimit(opts)`
+
+-   `opts` (object):
+    -   `tasks` (Array<() => Promise<T>>): An array of functions that each return a Promise.
+    -   `limit` (number): The maximum number of promises to execute in parallel.
+    -   `onTaskDone` (<R>(opts: { result: R }) => ValueOrPromise<void>, optional): A callback function that is executed whenever a task is completed.
+
+### Example
+
+```typescript
+import { executePromiseWithLimit, sleep } from '@venizia/ignis';
+
+const tasks = [
+  () => sleep(1000).then(() => 'Task 1 done'),
+  () => sleep(500).then(() => 'Task 2 done'),
+  () => sleep(1200).then(() => 'Task 3 done'),
+  () => sleep(800).then(() => 'Task 4 done'),
+];
+
+console.log('Starting tasks with a limit of 2...');
+
+const results = await executePromiseWithLimit({
+  tasks,
+  limit: 2,
+  onTaskDone: ({ result }) => {
+    console.log('A task finished:', result);
+  },
+});
+
+console.log('All tasks finished:', results);
+```
+
+## `isPromiseLike`
+
+A type guard function to check if a given value is a Promise-like object (i.e., it has a `then` method).
+
+```typescript
+import { isPromiseLike } from '@venizia/ignis';
+
+const a = Promise.resolve(1);
+const b = 2;
+
+if (isPromiseLike(a)) {
+  // This will run
+}
+
+if (isPromiseLike(b)) {
+  // This will not run
+}
+```
+
+## `transformValueOrPromise`
+
+This function applies a transformation function to a value that might be a direct value or a Promise.
+
+```typescript
+import { transformValueOrPromise, isPromiseLike } from '@venizia/ignis';
+
+const double = (n: number) => n * 2;
+
+const result1 = await transformValueOrPromise(5, double); // => 10
+const result2 = await transformValueOrPromise(Promise.resolve(5), double); // => 10
+```
+
+## `getDeepProperty`
+
+Safely retrieves a deeply nested property from an object using a dot-separated path string. It throws an error if any part of the path is null or undefined.
+
+```typescript
+import { getDeepProperty } from '@venizia/ignis';
+
+const obj = { a: { b: { c: 'hello' } } };
+
+const value = getDeepProperty(obj, 'a.b.c'); // => 'hello'
+```

package/wiki/references/utilities/request.md

@@ -0,0 +1,66 @@
+# Request Utility
+
+The Request utility provides functions for handling HTTP request data, such as parsing multipart form data.
+
+## `parseMultipartBody`
+
+The `parseMultipartBody` function is an asynchronous utility for parsing `multipart/form-data` request bodies, which is essential for handling file uploads. It can store the uploaded files in memory or on disk.
+
+### `parseMultipartBody(opts)`
+
+-   `opts` (object):
+    -   `context` (Hono.Context): The Hono context object for the current request.
+    -   `storage` ('memory' | 'disk', optional): The storage strategy for uploaded files. Defaults to `'memory'`.
+    -   `uploadDir` (string, optional): The directory to save files to when using the `'disk'` storage strategy. Defaults to `'./uploads'`.
+
+The function returns a `Promise` that resolves to an array of `IParsedFile` objects.
+
+### `IParsedFile` Interface
+
+-   `fieldname`: The name of the form field.
+-   `originalname`: The original name of the uploaded file.
+-   `encoding`: The file's encoding.
+-   `mimetype`: The MIME type of the file.
+-   `size`: The size of the file in bytes.
+-   `buffer` (Buffer, optional): The file's content as a Buffer (if `storage` is `'memory'`).
+-   `filename` (string, optional): The name of the file on disk (if `storage` is `'disk'`).
+-   `path` (string, optional): The full path to the file on disk (if `storage` is `'disk'`).
+
+### Example
+
+Here is an example of how to use `parseMultipartBody` in a controller to handle a file upload.
+
+```typescript
+import { BaseController, controller, ... } from '@venizia/ignis';
+import { parseMultipartBody } from '@venizia/ignis';
+
+@controller({ path: '/files' })
+export class FileController extends BaseController {
+  // ...
+  override binding() {
+    this.defineRoute({
+      configs: {
+        path: '/upload',
+        method: 'post',
+        // Note: You would typically define a request body schema
+        // for multipart/form-data in your OpenAPI spec.
+      },
+      handler: async (c) => {
+        try {
+          const files = await parseMultipartBody({
+            context: c,
+            storage: 'disk', // or 'memory'
+            uploadDir: './my-uploads',
+          });
+
+          console.log('Uploaded files:', files);
+
+          return c.json({ message: `${files.length} file(s) uploaded successfully.` });
+        } catch (error) {
+          return c.json({ message: 'Failed to upload files', error: error.message }, 500);
+        }
+      },
+    });
+  }
+}
+```

package/wiki/references/utilities/schema.md

@@ -0,0 +1,88 @@
+# Schema Utility
+
+The Schema utility provides a set of helper functions and predefined schemas for working with `zod` and `@hono/zod-openapi`. These utilities simplify the process of defining API request/response schemas and improve consistency in your API documentation.
+
+## `jsonContent`
+
+The `jsonContent` function creates a standard OpenAPI content object for `application/json` payloads.
+
+```typescript
+import { jsonContent, z } from '@venizia/ignis';
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+});
+
+const userResponse = {
+  description: 'A single user object',
+  ...jsonContent({ schema: UserSchema }),
+};
+```
+
+## `jsonResponse`
+
+The `jsonResponse` function generates a standard OpenAPI response object that includes a success (200 OK) response and a default error response for 4xx/5xx status codes.
+
+```typescript
+import { jsonResponse, z } from '@venizia/ignis';
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+});
+
+this.defineRoute({
+  configs: {
+    path: '/',
+    method: 'get',
+    responses: jsonResponse({
+      description: 'A single user object',
+      schema: UserSchema,
+    }),
+  },
+  // ...
+});
+```
+
+## `requiredString`
+
+This function creates a `zod` string schema that is non-empty and can be further constrained by length.
+
+```typescript
+import { requiredString } from '@venizia/ignis';
+
+const schema = z.object({
+  username: requiredString({ min: 3, max: 20 }),
+  password: requiredString({ min: 8 }),
+});
+```
+
+## Predefined Schemas
+
+The utility also provides several predefined schemas for common use cases.
+
+-   **`AnyObjectSchema`**: A flexible schema for any object (`z.object().catchall(z.any())`).
+-   **`IdParamsSchema`**: A schema for a numeric path parameter named `id`.
+-   **`UUIDParamsSchema`**: A schema for a UUID path parameter named `id`.
+
+### Example
+
+```typescript
+import { IdParamsSchema } from '@venizia/ignis';
+
+this.defineRoute({
+  configs: {
+    path: '/{id}',
+    method: 'get',
+    request: {
+      params: IdParamsSchema,
+    },
+    // ...
+  },
+  handler: (c) => {
+    const { id } = c.req.valid('param'); // id is a number
+    // ...
+  },
+});
+```