@zairakai/js-utils 1.0.0

package/dist/runtime.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runtime.ts
+var runtime_exports = {};
+__export(runtime_exports, {
+  data_get: () => data_get,
+  data_set: () => data_set,
+  isRecord: () => isRecord,
+  optional: () => optional,
+  retry: () => retry,
+  tap: () => tap,
+  throw_if: () => throw_if,
+  throw_unless: () => throw_unless,
+  value: () => value,
+  when: () => when
+});
+module.exports = __toCommonJS(runtime_exports);
+function isRecord(value2) {
+  return null !== value2 && "object" === typeof value2 && !Array.isArray(value2);
+}
+var tap = (value2, callback) => {
+  callback(value2);
+  return value2;
+};
+var when = (condition, onTrue, onFalse) => {
+  const shouldExecute = "function" === typeof condition ? condition() : Boolean(condition);
+  if (shouldExecute) {
+    return onTrue();
+  } else if (onFalse) {
+    return onFalse();
+  }
+  return void 0;
+};
+var value = (val) => {
+  return "function" === typeof val ? val() : val;
+};
+var data_get = (target, key, defaultValue = null) => {
+  if (!isRecord(target) && !Array.isArray(target)) {
+    return defaultValue;
+  }
+  const parts = Array.isArray(key) ? key : key.split(".");
+  let result = target;
+  for (const part of parts) {
+    if (!isRecord(result) && !Array.isArray(result)) {
+      return defaultValue;
+    }
+    if (part in result) {
+      result = result[part];
+    } else {
+      return defaultValue;
+    }
+  }
+  return result;
+};
+var data_set = (target, key, value2) => {
+  if (!isRecord(target) && !Array.isArray(target)) {
+    return target;
+  }
+  const parts = Array.isArray(key) ? key : key.split(".");
+  let current = target;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!isRecord(current)) {
+      break;
+    }
+    const currentRecord = current;
+    if (!(part in currentRecord) || !isRecord(currentRecord[part])) {
+      currentRecord[part] = {};
+    }
+    current = currentRecord[part];
+  }
+  if (isRecord(current)) {
+    ;
+    current[parts[parts.length - 1]] = value2;
+  }
+  return target;
+};
+var optional = (value2) => {
+  return value2 ?? null;
+};
+var retry = async (times, callback, sleepMilliseconds = 0) => {
+  let lastError;
+  for (let attempt = 1; attempt <= times; attempt++) {
+    try {
+      return await callback(attempt);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt < times && 0 < sleepMilliseconds) {
+        await new Promise((resolve) => setTimeout(resolve, sleepMilliseconds));
+      }
+    }
+  }
+  throw lastError ?? new Error(`Retry failed after ${times} attempts`);
+};
+var throw_if = (condition, exception) => {
+  if ("function" === typeof condition ? condition() : Boolean(condition)) {
+    throw "string" === typeof exception ? new Error(exception) : exception;
+  }
+};
+var throw_unless = (condition, exception) => {
+  if (!("function" === typeof condition ? condition() : Boolean(condition))) {
+    throw "string" === typeof exception ? new Error(exception) : exception;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  data_get,
+  data_set,
+  isRecord,
+  optional,
+  retry,
+  tap,
+  throw_if,
+  throw_unless,
+  value,
+  when
+});

package/dist/runtime.d.cts

@@ -0,0 +1,90 @@
+import { GenericRecord } from './types.cjs';
+
+/**
+ * Runtime utility functions inspired by Laravel
+ */
+/**
+ * Check if a value is a plain object (Record)
+ *
+ * @param {unknown} value The value to check
+ * @returns {value is GenericRecord} True if the value is a plain object
+ */
+declare function isRecord(value: unknown): value is GenericRecord;
+/**
+ * Execute a callback and return the given value
+ * Useful for side effects in a chain
+ *
+ * @param {T} value The value to pass to the callback
+ * @param {(value: T) => void} callback The callback to execute
+ * @returns {T} The original value
+ */
+declare const tap: <T>(value: T, callback: (value: T) => void) => T;
+/**
+ * Conditionally execute a callback
+ *
+ * @param {unknown} condition The condition to check (value or zero-arg function returning boolean)
+ * @param {() => R} onTrue The callback to execute if the condition is truthy
+ * @param {() => R} [onFalse] The callback to execute if the condition is falsy
+ * @returns {R | undefined} The result of the executed callback or undefined
+ */
+declare const when: <R>(condition: unknown, onTrue: () => R, onFalse?: () => R) => R | undefined;
+/**
+ * Return the first argument if it's truthy, otherwise return the second
+ *
+ * @param {T | (() => T)} val The value or a function that returns the value
+ * @returns {T} The resolved value
+ */
+declare const value: <T>(val: T | (() => T)) => T;
+/**
+ * Get an item from an array or object using dot notation
+ *
+ * @param {unknown} target The object or array to search
+ * @param {string | string[]} key The dot-notated key or an array of keys
+ * @param {unknown} [defaultValue=null] The default value to return if the key is not found
+ * @returns {unknown} The found value or the default value
+ */
+declare const data_get: (target: unknown, key: string | string[], defaultValue?: unknown) => unknown;
+/**
+ * Set an item in an array or object using dot notation
+ *
+ * @param {T} target The object or array to modify
+ * @param {string | string[]} key The dot-notated key or an array of keys
+ * @param {unknown} value The value to set
+ * @returns {T} The modified target
+ */
+declare const data_set: <T>(target: T, key: string | string[], value: unknown) => T;
+/**
+ * Returns the object if it exists, otherwise returns null (similar to optional() helper)
+ *
+ * @param {T} value The value to return if it exists
+ * @returns {T | null} The value or null
+ */
+declare const optional: <T>(value: T) => T | null;
+/**
+ * Execute a callback with retry logic
+ *
+ * @param {number} times The number of times to retry
+ * @param {(attempt: number) => Promise<T> | T} callback The callback to execute
+ * @param {number} [sleepMilliseconds=0] The amount of time to wait between retries
+ * @returns {Promise<T>} The result of the callback
+ * @throws {Error} If all attempts fail
+ */
+declare const retry: <T>(times: number, callback: (attempt: number) => Promise<T> | T, sleepMilliseconds?: number) => Promise<T>;
+/**
+ * Throw an error if a condition is met
+ *
+ * @param {unknown} condition The condition to check
+ * @param {Error | string} exception The error to throw or the error message
+ * @throws {Error} If the condition is met
+ */
+declare const throw_if: (condition: unknown, exception: Error | string) => void;
+/**
+ * Throw an error unless a condition is met
+ *
+ * @param {unknown} condition The condition to check
+ * @param {Error | string} exception The error to throw or the error message
+ * @throws {Error} If the condition is not met
+ */
+declare const throw_unless: (condition: unknown, exception: Error | string) => void;
+
+export { data_get, data_set, isRecord, optional, retry, tap, throw_if, throw_unless, value, when };

package/dist/runtime.d.ts

@@ -0,0 +1,90 @@
+import { GenericRecord } from './types.js';
+
+/**
+ * Runtime utility functions inspired by Laravel
+ */
+/**
+ * Check if a value is a plain object (Record)
+ *
+ * @param {unknown} value The value to check
+ * @returns {value is GenericRecord} True if the value is a plain object
+ */
+declare function isRecord(value: unknown): value is GenericRecord;
+/**
+ * Execute a callback and return the given value
+ * Useful for side effects in a chain
+ *
+ * @param {T} value The value to pass to the callback
+ * @param {(value: T) => void} callback The callback to execute
+ * @returns {T} The original value
+ */
+declare const tap: <T>(value: T, callback: (value: T) => void) => T;
+/**
+ * Conditionally execute a callback
+ *
+ * @param {unknown} condition The condition to check (value or zero-arg function returning boolean)
+ * @param {() => R} onTrue The callback to execute if the condition is truthy
+ * @param {() => R} [onFalse] The callback to execute if the condition is falsy
+ * @returns {R | undefined} The result of the executed callback or undefined
+ */
+declare const when: <R>(condition: unknown, onTrue: () => R, onFalse?: () => R) => R | undefined;
+/**
+ * Return the first argument if it's truthy, otherwise return the second
+ *
+ * @param {T | (() => T)} val The value or a function that returns the value
+ * @returns {T} The resolved value
+ */
+declare const value: <T>(val: T | (() => T)) => T;
+/**
+ * Get an item from an array or object using dot notation
+ *
+ * @param {unknown} target The object or array to search
+ * @param {string | string[]} key The dot-notated key or an array of keys
+ * @param {unknown} [defaultValue=null] The default value to return if the key is not found
+ * @returns {unknown} The found value or the default value
+ */
+declare const data_get: (target: unknown, key: string | string[], defaultValue?: unknown) => unknown;
+/**
+ * Set an item in an array or object using dot notation
+ *
+ * @param {T} target The object or array to modify
+ * @param {string | string[]} key The dot-notated key or an array of keys
+ * @param {unknown} value The value to set
+ * @returns {T} The modified target
+ */
+declare const data_set: <T>(target: T, key: string | string[], value: unknown) => T;
+/**
+ * Returns the object if it exists, otherwise returns null (similar to optional() helper)
+ *
+ * @param {T} value The value to return if it exists
+ * @returns {T | null} The value or null
+ */
+declare const optional: <T>(value: T) => T | null;
+/**
+ * Execute a callback with retry logic
+ *
+ * @param {number} times The number of times to retry
+ * @param {(attempt: number) => Promise<T> | T} callback The callback to execute
+ * @param {number} [sleepMilliseconds=0] The amount of time to wait between retries
+ * @returns {Promise<T>} The result of the callback
+ * @throws {Error} If all attempts fail
+ */
+declare const retry: <T>(times: number, callback: (attempt: number) => Promise<T> | T, sleepMilliseconds?: number) => Promise<T>;
+/**
+ * Throw an error if a condition is met
+ *
+ * @param {unknown} condition The condition to check
+ * @param {Error | string} exception The error to throw or the error message
+ * @throws {Error} If the condition is met
+ */
+declare const throw_if: (condition: unknown, exception: Error | string) => void;
+/**
+ * Throw an error unless a condition is met
+ *
+ * @param {unknown} condition The condition to check
+ * @param {Error | string} exception The error to throw or the error message
+ * @throws {Error} If the condition is not met
+ */
+declare const throw_unless: (condition: unknown, exception: Error | string) => void;
+
+export { data_get, data_set, isRecord, optional, retry, tap, throw_if, throw_unless, value, when };

package/dist/runtime.js

@@ -0,0 +1,24 @@
+import {
+  data_get,
+  data_set,
+  isRecord,
+  optional,
+  retry,
+  tap,
+  throw_if,
+  throw_unless,
+  value,
+  when
+} from "./chunk-ZJPKS2MQ.js";
+export {
+  data_get,
+  data_set,
+  isRecord,
+  optional,
+  retry,
+  tap,
+  throw_if,
+  throw_unless,
+  value,
+  when
+};

package/dist/schemas.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/schemas.ts
+var schemas_exports = {};
+__export(schemas_exports, {
+  ApiResponseSchema: () => ApiResponseSchema,
+  DateSchema: () => DateSchema,
+  EmailSchema: () => EmailSchema,
+  PaginatedResponseSchema: () => PaginatedResponseSchema,
+  PaginationSchema: () => PaginationSchema,
+  PhoneSchema: () => PhoneSchema,
+  UrlSchema: () => UrlSchema,
+  safeValidateSchema: () => safeValidateSchema,
+  validateSchema: () => validateSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+var EmailSchema = import_zod.z.string().email("Invalid email format").min(1, "Email is required");
+var PhoneSchema = import_zod.z.string().regex(/^\+?[1-9]\d{1,14}$/, "Invalid phone number format");
+var UrlSchema = import_zod.z.string().url("Invalid URL format");
+var DateSchema = import_zod.z.union([
+  import_zod.z.string().datetime(),
+  import_zod.z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Invalid date format (YYYY-MM-DD)"),
+  import_zod.z.date()
+]);
+var ApiResponseSchema = (dataSchema) => import_zod.z.object({
+  success: import_zod.z.boolean(),
+  data: dataSchema.optional(),
+  message: import_zod.z.string().optional(),
+  errors: import_zod.z.array(import_zod.z.string()).optional()
+});
+var PaginationSchema = import_zod.z.object({
+  page: import_zod.z.number().int().positive().default(1),
+  perPage: import_zod.z.number().int().min(1).max(100).default(15),
+  total: import_zod.z.number().int().nonnegative(),
+  lastPage: import_zod.z.number().int().positive()
+});
+var PaginatedResponseSchema = (itemSchema) => import_zod.z.object({
+  data: import_zod.z.array(itemSchema),
+  pagination: PaginationSchema
+});
+var validateSchema = (schema, data) => {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const errors = result.error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+    throw new Error(`Validation failed: ${errors.join(", ")}`);
+  }
+  return result.data;
+};
+var safeValidateSchema = (schema, data) => {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errors = result.error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+  return { success: false, errors };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiResponseSchema,
+  DateSchema,
+  EmailSchema,
+  PaginatedResponseSchema,
+  PaginationSchema,
+  PhoneSchema,
+  UrlSchema,
+  safeValidateSchema,
+  validateSchema
+});

package/dist/schemas.d.cts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+
+/**
+ * Runtime type validation schemas using Zod
+ * Provides runtime type checking that persists after TypeScript compilation
+ */
+
+/**
+ * Email validation schema
+ */
+declare const EmailSchema: z.ZodString;
+/**
+ * Phone validation schema (E.164 format)
+ */
+declare const PhoneSchema: z.ZodString;
+/**
+ * URL validation schema
+ */
+declare const UrlSchema: z.ZodString;
+/**
+ * Date validation schema (ISO datetime, YYYY-MM-DD, or Date object)
+ */
+declare const DateSchema: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodDate]>;
+/**
+ * API Response schema factory
+ *
+ * @param {T} dataSchema The schema for the data property
+ * @returns {z.ZodObject} The API response schema
+ */
+declare const ApiResponseSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodOptional<T>;
+    message: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Pagination schema
+ */
+declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    perPage: z.ZodDefault<z.ZodNumber>;
+    total: z.ZodNumber;
+    lastPage: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Paginated response schema factory
+ *
+ * @param {T} itemSchema The schema for individual items in the data array
+ * @returns {z.ZodObject} The paginated response schema
+ */
+declare const PaginatedResponseSchema: <T extends z.ZodTypeAny>(itemSchema: T) => z.ZodObject<{
+    data: z.ZodArray<T>;
+    pagination: z.ZodObject<{
+        page: z.ZodDefault<z.ZodNumber>;
+        perPage: z.ZodDefault<z.ZodNumber>;
+        total: z.ZodNumber;
+        lastPage: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Type inferred from EmailSchema
+ */
+type Email = z.infer<typeof EmailSchema>;
+/**
+ * Type inferred from PhoneSchema
+ */
+type Phone = z.infer<typeof PhoneSchema>;
+/**
+ * Type inferred from UrlSchema
+ */
+type Url = z.infer<typeof UrlSchema>;
+/**
+ * Type inferred from ApiResponseSchema
+ */
+type ApiResponse<T> = z.infer<ReturnType<typeof ApiResponseSchema<z.ZodType<T>>>>;
+/**
+ * Type inferred from PaginationSchema
+ */
+type Pagination = z.infer<typeof PaginationSchema>;
+/**
+ * Type inferred from PaginatedResponseSchema
+ */
+type PaginatedResponse<T> = z.infer<ReturnType<typeof PaginatedResponseSchema<z.ZodType<T>>>>;
+/**
+ * Validates data against a schema and throws detailed errors
+ *
+ * @param {z.ZodSchema<T>} schema The schema to validate against
+ * @param {unknown} data The data to validate
+ * @returns {T} The validated data
+ * @throws {Error} If validation fails
+ */
+declare const validateSchema: <T>(schema: z.ZodSchema<T>, data: unknown) => T;
+/**
+ * Validates data against a schema and returns result with success flag
+ *
+ * @param {z.ZodSchema<T>} schema The schema to validate against
+ * @param {unknown} data The data to validate
+ * @returns {{ success: true; data: T } | { success: false; errors: string[] }} The validation result
+ */
+declare const safeValidateSchema: <T>(schema: z.ZodSchema<T>, data: unknown) => {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: string[];
+};
+
+export { type ApiResponse, ApiResponseSchema, DateSchema, type Email, EmailSchema, type PaginatedResponse, PaginatedResponseSchema, type Pagination, PaginationSchema, type Phone, PhoneSchema, type Url, UrlSchema, safeValidateSchema, validateSchema };

package/dist/schemas.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+
+/**
+ * Runtime type validation schemas using Zod
+ * Provides runtime type checking that persists after TypeScript compilation
+ */
+
+/**
+ * Email validation schema
+ */
+declare const EmailSchema: z.ZodString;
+/**
+ * Phone validation schema (E.164 format)
+ */
+declare const PhoneSchema: z.ZodString;
+/**
+ * URL validation schema
+ */
+declare const UrlSchema: z.ZodString;
+/**
+ * Date validation schema (ISO datetime, YYYY-MM-DD, or Date object)
+ */
+declare const DateSchema: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodDate]>;
+/**
+ * API Response schema factory
+ *
+ * @param {T} dataSchema The schema for the data property
+ * @returns {z.ZodObject} The API response schema
+ */
+declare const ApiResponseSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodOptional<T>;
+    message: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Pagination schema
+ */
+declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    perPage: z.ZodDefault<z.ZodNumber>;
+    total: z.ZodNumber;
+    lastPage: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Paginated response schema factory
+ *
+ * @param {T} itemSchema The schema for individual items in the data array
+ * @returns {z.ZodObject} The paginated response schema
+ */
+declare const PaginatedResponseSchema: <T extends z.ZodTypeAny>(itemSchema: T) => z.ZodObject<{
+    data: z.ZodArray<T>;
+    pagination: z.ZodObject<{
+        page: z.ZodDefault<z.ZodNumber>;
+        perPage: z.ZodDefault<z.ZodNumber>;
+        total: z.ZodNumber;
+        lastPage: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Type inferred from EmailSchema
+ */
+type Email = z.infer<typeof EmailSchema>;
+/**
+ * Type inferred from PhoneSchema
+ */
+type Phone = z.infer<typeof PhoneSchema>;
+/**
+ * Type inferred from UrlSchema
+ */
+type Url = z.infer<typeof UrlSchema>;
+/**
+ * Type inferred from ApiResponseSchema
+ */
+type ApiResponse<T> = z.infer<ReturnType<typeof ApiResponseSchema<z.ZodType<T>>>>;
+/**
+ * Type inferred from PaginationSchema
+ */
+type Pagination = z.infer<typeof PaginationSchema>;
+/**
+ * Type inferred from PaginatedResponseSchema
+ */
+type PaginatedResponse<T> = z.infer<ReturnType<typeof PaginatedResponseSchema<z.ZodType<T>>>>;
+/**
+ * Validates data against a schema and throws detailed errors
+ *
+ * @param {z.ZodSchema<T>} schema The schema to validate against
+ * @param {unknown} data The data to validate
+ * @returns {T} The validated data
+ * @throws {Error} If validation fails
+ */
+declare const validateSchema: <T>(schema: z.ZodSchema<T>, data: unknown) => T;
+/**
+ * Validates data against a schema and returns result with success flag
+ *
+ * @param {z.ZodSchema<T>} schema The schema to validate against
+ * @param {unknown} data The data to validate
+ * @returns {{ success: true; data: T } | { success: false; errors: string[] }} The validation result
+ */
+declare const safeValidateSchema: <T>(schema: z.ZodSchema<T>, data: unknown) => {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: string[];
+};
+
+export { type ApiResponse, ApiResponseSchema, DateSchema, type Email, EmailSchema, type PaginatedResponse, PaginatedResponseSchema, type Pagination, PaginationSchema, type Phone, PhoneSchema, type Url, UrlSchema, safeValidateSchema, validateSchema };

package/dist/schemas.js

@@ -0,0 +1,22 @@
+import {
+  ApiResponseSchema,
+  DateSchema,
+  EmailSchema,
+  PaginatedResponseSchema,
+  PaginationSchema,
+  PhoneSchema,
+  UrlSchema,
+  safeValidateSchema,
+  validateSchema
+} from "./chunk-W6JEMFAF.js";
+export {
+  ApiResponseSchema,
+  DateSchema,
+  EmailSchema,
+  PaginatedResponseSchema,
+  PaginationSchema,
+  PhoneSchema,
+  UrlSchema,
+  safeValidateSchema,
+  validateSchema
+};