ZTK - Zaions Tool Kit

A comprehensive TypeScript utility library providing a wide range of tools for modern web development.

Features

• 🔒 Secure Cryptography - AES encryption/decryption utilities
• 🧩 Type Safety - Extensive TypeScript type definitions and enums
• 🛠️ Utility Functions - 100+ helper functions for common tasks
• 🎮 Gaming Support - Specialized utilities for gaming applications
• 🔍 Validation - Form validation, permission checking, and more
• 📦 Modular Design - Import only what you need

Installation

# Using npm
npm install zaions-tool-kit

# Using yarn
yarn add zaions-tool-kit

# Using pnpm
pnpm add zaions-tool-kit

Quick Start

import { configureZTK, isValidEmail, generateUUID } from 'zaions-tool-kit';

// Configure the library (required for crypto functions)
configureZTK({
  cryptoSecret: 'your-secure-secret-key',
});

// Use utility functions
const email = '[email protected]';
console.log(isValidEmail(email)); // true

const uuid = generateUUID();
console.log(uuid); // e.g., '550e8400-e29b-41d4-a716-446655440000'

Core Modules

Cryptography

Secure encryption and decryption utilities:

import {
  encryptData,
  decryptData,
  encryptWithSecretKey,
  decryptWithSecretKey,
} from 'zaions-tool-kit';

// Using explicit secret key
const encrypted = encryptData('sensitive data', 'your-secret-key');
const decrypted = decryptData(encrypted, 'your-secret-key');

// Using configured secret key
const encryptedWithConfig = encryptWithSecretKey('sensitive data');
const decryptedWithConfig = decryptWithSecretKey(encryptedWithConfig);

See Cryptography Documentation for more details.

Validation

Comprehensive validation utilities:

import {
  isValidEmail,
  isValidUrl,
  validatePhoneNumber,
  validateRequiredPermissions,
  PermissionCheckModeEnum,
} from 'zaions-tool-kit';

// Basic validation
isValidEmail('[email protected]'); // true
isValidUrl('https://example.com'); // true
validatePhoneNumber('+923001234567'); // true

// Permission validation
validateRequiredPermissions({
  userPermissions: ['read', 'write'],
  requiredPermissions: ['read'],
  checkModeForRequiredPermissions: PermissionCheckModeEnum.every,
}); // true

See Validation Documentation for more details.

String Manipulation

Utilities for working with strings:

import {
  truncateString,
  convertToTitleCase,
  generateSlug,
  escapeRegex,
  containSpecialCharacters,
} from 'zaions-tool-kit';

truncateString('This is a long text that will be truncated', 20); // 'This is a long text...'
convertToTitleCase('hello world'); // 'Hello World'
generateSlug('This is a title!'); // 'this-is-a-title'
escapeRegex('(test)'); // '\\(test\\)'
containSpecialCharacters('test@123'); // true

See String Utilities Documentation for more details.

Array Utilities

Functions for array manipulation:

import {
  flattenArray,
  arrayMoveMutable,
  arrayMoveImmutable,
  checkEqualityOfTwoArray,
} from 'zaions-tool-kit';

// Flatten nested arrays
flattenArray([1, [2, [3, 4]], 5]); // [1, 2, 3, 4, 5]

// Move array elements (mutating original)
const arr1 = [1, 2, 3, 4];
arrayMoveMutable(arr1, 0, 2);
console.log(arr1); // [2, 3, 1, 4]

// Move array elements (non-mutating)
const arr2 = [1, 2, 3, 4];
const newArr = arrayMoveImmutable(arr2, 0, 2);
console.log(newArr); // [2, 3, 1, 4]
console.log(arr2); // [1, 2, 3, 4] (unchanged)

// Compare arrays
checkEqualityOfTwoArray([1, 2, 3], [1, 2, 3]); // true

See Array Utilities Documentation for more details.

Type Checking

Robust type checking utilities:

import {
  isArray,
  isObject,
  isFunction,
  isNullOrUndefined,
  isNotNullOrUndefined,
  isStringVariable,
  isZValidNumber,
} from 'zaions-tool-kit';

isArray([1, 2, 3]); // true
isArray([1, 2, 3], true); // true (checks length > 0)
isObject({ name: 'John' }); // true
isFunction(() => {}); // true
isNullOrUndefined(null); // true
isNotNullOrUndefined('value'); // true
isStringVariable('test'); // true
isZValidNumber(123); // true

See Type Checking Documentation for more details.

Date and Time

Utilities for working with dates and times:

import {
  dayjs,
  dateFormat,
  getDateFromFrbTimestamp,
  convertToDateTimestampToStoreInDB,
  getRemainingTimeForCountDown,
} from 'zaions-tool-kit';

// Format dates
dateFormat(new Date(), 'YYYY-MM-DD'); // e.g., '2023-05-15'

// Work with Firebase timestamps
const timestamp = convertToDateTimestampToStoreInDB(new Date());
const date = getDateFromFrbTimestamp(timestamp);

// Get countdown time
const remaining = getRemainingTimeForCountDown(new Date(Date.now() + 3600000));
console.log(remaining); // e.g., { hours: 1, minutes: 0, seconds: 0 }

See Date Utilities Documentation for more details.

URL Handling

Functions for working with URLs:

import {
  isValidUrl,
  addUrlProtocolHandler,
  containQueryParams,
  hasLeadingOrTrailingSlash,
  removeLeadingTrailingBackslash,
  replaceUrlDynamicParts,
} from 'zaions-tool-kit';

isValidUrl('https://example.com'); // true
addUrlProtocolHandler('example.com'); // 'https://example.com'
containQueryParams('https://example.com?param=value'); // true
hasLeadingOrTrailingSlash('/path/'); // true
removeLeadingTrailingBackslash('/path/'); // 'path'
replaceUrlDynamicParts('/users/:id/profile', { id: '123' }); // '/users/123/profile'

See URL Utilities Documentation for more details.

CSS Class Name Utilities

Utilities for managing CSS class names:

import { classNames, classNamesBind, classNamesDedupe } from 'zaions-tool-kit';

classNames('foo', 'bar'); // 'foo bar'
classNames('foo', { bar: true, baz: false }); // 'foo bar'
classNames({ 'foo-bar': true }); // 'foo-bar'
classNames({ 'foo-bar': false }); // ''
classNames({ foo: true }, { bar: true }); // 'foo bar'
classNames(['foo', 'bar']); // 'foo bar'

// With binding
const cx = classNamesBind();
cx('foo', { bar: true }); // 'foo bar'

// Remove duplicates
classNamesDedupe('foo foo bar'); // 'foo bar'

See CSS Class Utilities Documentation for more details.

Coupon Code Generation

Utilities for generating and validating coupon codes:

import {
  generateCouponCode,
  validateCouponCode,
  checkIfCouponCodeHasBadWord,
} from 'zaions-tool-kit';

// Generate a coupon code
const coupon = generateCouponCode(); // e.g., 'ABCD-EFGH-IJKL'
const customCoupon = generateCouponCode({ parts: 2, partLen: 5 }); // e.g., 'ABCDE-FGHIJ'

// Validate a coupon code
validateCouponCode('ABCD-EFGH-IJKL'); // true

// Check for inappropriate words
checkIfCouponCodeHasBadWord('ABCD-EFGH-IJKL'); // false

See Coupon Code Documentation for more details.

Enums

ZTK provides a wide range of enums for consistent type-safe coding:

import {
  _UserRoleEnum,
  PermissionEnum,
  RoleEnum,
  FormFieldsEnum,
  ResponseStatusEnum,
  varTypesEnum,
} from 'zaions-tool-kit';

// User roles
const adminRole = _UserRoleEnum.admin; // 2

// Permission checking
const readPermission = PermissionEnum.read; // 1

// Form fields
const emailField = FormFieldsEnum.email; // 'email'

// Variable types
const stringType = varTypesEnum.STRING; // 'string'

See Enums Documentation for a complete list of available enums.

Types

ZTK includes many TypeScript types and interfaces:

import type {
  IGenericObject,
  IHasRequiredPermissions,
  IPaginationOptions,
  DBItemGenericDataType,
  FormItemGenericDataType,
} from 'zaions-tool-kit';

// Generic object
const obj: IGenericObject = { key: 'value' };

// Pagination options
const pagination: IPaginationOptions = {
  page: 1,
  limit: 10,
  sortBy: 'createdAt',
  sortDirection: 'desc',
};

See Types Documentation for more details on available types.

Gaming Support

ZTK includes specialized utilities for gaming applications:

import {
  // Play and Win module
  IGame,
  IGameRoom,
  ITransaction,
  IUser,
  ITopUp,
  IWithdraw,
} from 'zaions-tool-kit/play-and-win';

See Gaming Support Documentation for more details.

Permission Management

ZTK provides a robust permission management system:

import {
  validateRequiredPermissions,
  validateExcludedPermissions,
  hasPermission,
  getPermissions,
  mapPermissionsToStrings,
  PermissionCheckModeEnum,
  PermissionEnum,
} from 'zaions-tool-kit';

// Check if user has all required permissions
const hasAllPermissions = validateRequiredPermissions({
  userPermissions: [PermissionEnum.read, PermissionEnum.write],
  requiredPermissions: [PermissionEnum.read],
  checkModeForRequiredPermissions: PermissionCheckModeEnum.every,
}); // true

// Check if user has any of the required permissions
const hasAnyPermission = validateRequiredPermissions({
  userPermissions: [PermissionEnum.read],
  requiredPermissions: [PermissionEnum.read, PermissionEnum.write],
  checkModeForRequiredPermissions: PermissionCheckModeEnum.any,
}); // true

// Check if user doesn't have excluded permissions
const hasNoExcludedPermissions = validateExcludedPermissions({
  userPermissions: [PermissionEnum.read],
  excludedPermissions: [PermissionEnum.delete],
}); // true

// Check for a specific permission
const canRead = hasPermission({
  userPermissions: [PermissionEnum.read, PermissionEnum.write],
  permission: PermissionEnum.read,
}); // true

See Permission Management Documentation for more details.

Form Validation

ZTK includes utilities for form validation:

import {
  validateEmail,
  validatePhoneNumber,
  validateURL,
  fieldsValidation,
} from 'zaions-tool-kit';

// Validate email
validateEmail('[email protected]'); // true

// Validate phone number
validatePhoneNumber('+923001234567'); // true

// Validate URL
validateURL('https://example.com'); // true

// Access validation rules
const titleRules = fieldsValidation.generic.title;
console.log(titleRules.min.val); // 1
console.log(titleRules.max.val); // 100

See Form Validation Documentation for more details.

Image Processing

Utilities for working with images:

import {
  getImageDimensions,
  getImageAspectRatio,
  imageTypeAllowed,
  imageUrlToBase64,
  getImageBase64Url,
  validateFileBeforeUpload,
  allowedImageTypes,
} from 'zaions-tool-kit';

// Check if image type is allowed
imageTypeAllowed('image/jpeg'); // true

// Get image dimensions from a File object
getImageDimensions(imageFile).then((dimensions) => {
  console.log(dimensions.width, dimensions.height);
});

// Convert image URL to base64
imageUrlToBase64('https://example.com/image.jpg').then((base64) => {
  console.log(base64); // data:image/jpeg;base64,...
});

// Validate file before upload
validateFileBeforeUpload({
  file: imageFile,
  maxSizeInMB: 2,
  allowedTypes: allowedImageTypes,
}).then((result) => {
  if (result.isValid) {
    // File is valid
  } else {
    console.error(result.errorMessage);
  }
});

See Image Processing Documentation for more details.

Firebase Utilities

ZTK includes utilities for working with Firebase:

import {
  frbCollectionQueryDefaults,
  getDateFromFrbTimestamp,
  convertToDateTimestampToStoreInDB,
  FrbOrderbyDirectionEnum,
  FrbWhereConditionEnum,
  DBColumnKeysShortFormEnum,
} from 'zaions-tool-kit';

// Default query parameters
const defaults = frbCollectionQueryDefaults;
console.log(defaults.limit); // 10

// Convert JavaScript Date to Firebase timestamp
const timestamp = convertToDateTimestampToStoreInDB(new Date());

// Convert Firebase timestamp to JavaScript Date
const date = getDateFromFrbTimestamp(timestamp);

// Use Firebase enums
const orderDirection = FrbOrderbyDirectionEnum.desc;
const whereCondition = FrbWhereConditionEnum.equalTo;

See Firebase Utilities Documentation for more details.

Specialized Modules

ZTK includes specialized modules for specific use cases:

Play and Win Module

import {
  IGame,
  IGameRoom,
  IUser,
  ITransaction,
} from 'zaions-tool-kit/play-and-win';

Roommate Module

import {
  ConstellationsEnum,
  constellationsVal,
} from 'zaions-tool-kit/roommate';

Zod Integration

import { numericEnum } from 'zaions-tool-kit/require-package/zod';

Day.js Integration

import { dayjs } from 'zaions-tool-kit/require-package/dayjs';

See Specialized Modules Documentation for more details.

Browser Compatibility

ZTK is compatible with all modern browsers (Chrome, Firefox, Safari, Edge) and Node.js environments.

Tree-Shaking

ZTK is designed with tree-shaking in mind. When using a bundler like webpack, Rollup, or Parcel, only the functions you actually import will be included in your final bundle.

Documentation

For complete documentation, visit our documentation site.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Zaions

Zaions Tool Kit - this is generic tool kit package created by team working at Zaions (https://zaions.com)

All of our packages are developed with 100% typescript support/safety, mean if you are a types lover then you will love it as well :)

there are other packages named "zaions-express-tool-kit", "zaions-react-tool-kit", and "zaions-react-ui-kit". while this package is generic and contains code which will work both on frontend (reactjs/typescript) as well as on backend (nodejs/typescript) the other packages are specific to server side or client side (due to the dependencies used in them and their usage nature

• zaions-tool-kit
  • our most generic package, can be used in frontend or backend, frontend/backend compatible.
  • contains a lot of helper functions, utils, messages, constants and a lot more.
  • why to use this?
    • so you don't write the common helpers/constants/utils/more each time in each and every project, instead you use this one package which will help you everywhere.
• zaions-express-tool-kit
  • this package is for nodejs projects mainly using expressJs.
• zaions-react-tool-kit
  • this package is for react project, it does not contains UI components (we have a separate package for that), instead this one contains helper functions and many other help full utils to make it easy for you to create react apps.
• zaions-react-ui-kit
  • As the name suggests, it's our UI library.
  • But wait, it's not just a UI library, in fact it's a complete UI solution, with higher order components to help you detech network connectivity, errors pages to help you show meaning full errors to users when there's an error and even fully functional working pages, including (not limited to), auth pages, register, login and forget password page and much more, and it contains a lot of code to help you with form management and a lot more.

We hope you will love this and all other packages we have developed for you

please do react out if you face any issue in packages we deliver

Once again have fun while working with these packages and let us know your feedback, it keeps us motivated. Have a great day :)