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

1# Using npm
2npm install zaions-tool-kit
3
4# Using yarn
5yarn add zaions-tool-kit
6
7# Using pnpm
8pnpm add zaions-tool-kit

Quick Start

1import { configureZTK, isValidEmail, generateUUID } from 'zaions-tool-kit';
2
3// Configure the library (required for crypto functions)
4configureZTK({
5  cryptoSecret: 'your-secure-secret-key',
6});
7
8// Use utility functions
9const email = 'test@example.com';
10console.log(isValidEmail(email)); // true
11
12const uuid = generateUUID();
13console.log(uuid); // e.g., '550e8400-e29b-41d4-a716-446655440000'

Core Modules

Cryptography

Secure encryption and decryption utilities:

1import {
2  encryptData,
3  decryptData,
4  encryptWithSecretKey,
5  decryptWithSecretKey,
6} from 'zaions-tool-kit';
7
8// Using explicit secret key
9const encrypted = encryptData('sensitive data', 'your-secret-key');
10const decrypted = decryptData(encrypted, 'your-secret-key');
11
12// Using configured secret key
13const encryptedWithConfig = encryptWithSecretKey('sensitive data');
14const decryptedWithConfig = decryptWithSecretKey(encryptedWithConfig);

See Cryptography Documentation for more details.

Validation

Comprehensive validation utilities:

1import {
2  isValidEmail,
3  isValidUrl,
4  validatePhoneNumber,
5  validateRequiredPermissions,
6  PermissionCheckModeEnum,
7} from 'zaions-tool-kit';
8
9// Basic validation
10isValidEmail('user@example.com'); // true
11isValidUrl('https://example.com'); // true
12validatePhoneNumber('+923001234567'); // true
13
14// Permission validation
15validateRequiredPermissions({
16  userPermissions: ['read', 'write'],
17  requiredPermissions: ['read'],
18  checkModeForRequiredPermissions: PermissionCheckModeEnum.every,
19}); // true

See Validation Documentation for more details.

String Manipulation

Utilities for working with strings:

1import {
2  truncateString,
3  convertToTitleCase,
4  generateSlug,
5  escapeRegex,
6  containSpecialCharacters,
7} from 'zaions-tool-kit';
8
9truncateString('This is a long text that will be truncated', 20); // 'This is a long text...'
10convertToTitleCase('hello world'); // 'Hello World'
11generateSlug('This is a title!'); // 'this-is-a-title'
12escapeRegex('(test)'); // '\\(test\\)'
13containSpecialCharacters('test@123'); // true

See String Utilities Documentation for more details.

Array Utilities

Functions for array manipulation:

1import {
2  flattenArray,
3  arrayMoveMutable,
4  arrayMoveImmutable,
5  checkEqualityOfTwoArray,
6} from 'zaions-tool-kit';
7
8// Flatten nested arrays
9flattenArray([1, [2, [3, 4]], 5]); // [1, 2, 3, 4, 5]
10
11// Move array elements (mutating original)
12const arr1 = [1, 2, 3, 4];
13arrayMoveMutable(arr1, 0, 2);
14console.log(arr1); // [2, 3, 1, 4]
15
16// Move array elements (non-mutating)
17const arr2 = [1, 2, 3, 4];
18const newArr = arrayMoveImmutable(arr2, 0, 2);
19console.log(newArr); // [2, 3, 1, 4]
20console.log(arr2); // [1, 2, 3, 4] (unchanged)
21
22// Compare arrays
23checkEqualityOfTwoArray([1, 2, 3], [1, 2, 3]); // true

See Array Utilities Documentation for more details.

Type Checking

Robust type checking utilities:

1import {
2  isArray,
3  isObject,
4  isFunction,
5  isNullOrUndefined,
6  isNotNullOrUndefined,
7  isStringVariable,
8  isZValidNumber,
9} from 'zaions-tool-kit';
10
11isArray([1, 2, 3]); // true
12isArray([1, 2, 3], true); // true (checks length > 0)
13isObject({ name: 'John' }); // true
14isFunction(() => {}); // true
15isNullOrUndefined(null); // true
16isNotNullOrUndefined('value'); // true
17isStringVariable('test'); // true
18isZValidNumber(123); // true

See Type Checking Documentation for more details.

Date and Time

Utilities for working with dates and times:

1import {
2  dayjs,
3  dateFormat,
4  getDateFromFrbTimestamp,
5  convertToDateTimestampToStoreInDB,
6  getRemainingTimeForCountDown,
7} from 'zaions-tool-kit';
8
9// Format dates
10dateFormat(new Date(), 'YYYY-MM-DD'); // e.g., '2023-05-15'
11
12// Work with Firebase timestamps
13const timestamp = convertToDateTimestampToStoreInDB(new Date());
14const date = getDateFromFrbTimestamp(timestamp);
15
16// Get countdown time
17const remaining = getRemainingTimeForCountDown(new Date(Date.now() + 3600000));
18console.log(remaining); // e.g., { hours: 1, minutes: 0, seconds: 0 }

See Date Utilities Documentation for more details.

URL Handling

Functions for working with URLs:

1import {
2  isValidUrl,
3  addUrlProtocolHandler,
4  containQueryParams,
5  hasLeadingOrTrailingSlash,
6  removeLeadingTrailingBackslash,
7  replaceUrlDynamicParts,
8} from 'zaions-tool-kit';
9
10isValidUrl('https://example.com'); // true
11addUrlProtocolHandler('example.com'); // 'https://example.com'
12containQueryParams('https://example.com?param=value'); // true
13hasLeadingOrTrailingSlash('/path/'); // true
14removeLeadingTrailingBackslash('/path/'); // 'path'
15replaceUrlDynamicParts('/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:

1import { classNames, classNamesBind, classNamesDedupe } from 'zaions-tool-kit';
2
3classNames('foo', 'bar'); // 'foo bar'
4classNames('foo', { bar: true, baz: false }); // 'foo bar'
5classNames({ 'foo-bar': true }); // 'foo-bar'
6classNames({ 'foo-bar': false }); // ''
7classNames({ foo: true }, { bar: true }); // 'foo bar'
8classNames(['foo', 'bar']); // 'foo bar'
9
10// With binding
11const cx = classNamesBind();
12cx('foo', { bar: true }); // 'foo bar'
13
14// Remove duplicates
15classNamesDedupe('foo foo bar'); // 'foo bar'

See CSS Class Utilities Documentation for more details.

Coupon Code Generation

Utilities for generating and validating coupon codes:

1import {
2  generateCouponCode,
3  validateCouponCode,
4  checkIfCouponCodeHasBadWord,
5} from 'zaions-tool-kit';
6
7// Generate a coupon code
8const coupon = generateCouponCode(); // e.g., 'ABCD-EFGH-IJKL'
9const customCoupon = generateCouponCode({ parts: 2, partLen: 5 }); // e.g., 'ABCDE-FGHIJ'
10
11// Validate a coupon code
12validateCouponCode('ABCD-EFGH-IJKL'); // true
13
14// Check for inappropriate words
15checkIfCouponCodeHasBadWord('ABCD-EFGH-IJKL'); // false

See Coupon Code Documentation for more details.

Enums

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

1import {
2  _UserRoleEnum,
3  PermissionEnum,
4  RoleEnum,
5  FormFieldsEnum,
6  ResponseStatusEnum,
7  varTypesEnum,
8} from 'zaions-tool-kit';
9
10// User roles
11const adminRole = _UserRoleEnum.admin; // 2
12
13// Permission checking
14const readPermission = PermissionEnum.read; // 1
15
16// Form fields
17const emailField = FormFieldsEnum.email; // 'email'
18
19// Variable types
20const stringType = varTypesEnum.STRING; // 'string'

See Enums Documentation for a complete list of available enums.

Types

ZTK includes many TypeScript types and interfaces:

1import type {
2  IGenericObject,
3  IHasRequiredPermissions,
4  IPaginationOptions,
5  DBItemGenericDataType,
6  FormItemGenericDataType,
7} from 'zaions-tool-kit';
8
9// Generic object
10const obj: IGenericObject = { key: 'value' };
11
12// Pagination options
13const pagination: IPaginationOptions = {
14  page: 1,
15  limit: 10,
16  sortBy: 'createdAt',
17  sortDirection: 'desc',
18};

See Types Documentation for more details on available types.

Gaming Support

ZTK includes specialized utilities for gaming applications:

1import {
2  // Play and Win module
3  IGame,
4  IGameRoom,
5  ITransaction,
6  IUser,
7  ITopUp,
8  IWithdraw,
9} from 'zaions-tool-kit/play-and-win';

See Gaming Support Documentation for more details.

Permission Management

ZTK provides a robust permission management system:

1import {
2  validateRequiredPermissions,
3  validateExcludedPermissions,
4  hasPermission,
5  getPermissions,
6  mapPermissionsToStrings,
7  PermissionCheckModeEnum,
8  PermissionEnum,
9} from 'zaions-tool-kit';
10
11// Check if user has all required permissions
12const hasAllPermissions = validateRequiredPermissions({
13  userPermissions: [PermissionEnum.read, PermissionEnum.write],
14  requiredPermissions: [PermissionEnum.read],
15  checkModeForRequiredPermissions: PermissionCheckModeEnum.every,
16}); // true
17
18// Check if user has any of the required permissions
19const hasAnyPermission = validateRequiredPermissions({
20  userPermissions: [PermissionEnum.read],
21  requiredPermissions: [PermissionEnum.read, PermissionEnum.write],
22  checkModeForRequiredPermissions: PermissionCheckModeEnum.any,
23}); // true
24
25// Check if user doesn't have excluded permissions
26const hasNoExcludedPermissions = validateExcludedPermissions({
27  userPermissions: [PermissionEnum.read],
28  excludedPermissions: [PermissionEnum.delete],
29}); // true
30
31// Check for a specific permission
32const canRead = hasPermission({
33  userPermissions: [PermissionEnum.read, PermissionEnum.write],
34  permission: PermissionEnum.read,
35}); // true

See Permission Management Documentation for more details.

Form Validation

ZTK includes utilities for form validation:

1import {
2  validateEmail,
3  validatePhoneNumber,
4  validateURL,
5  fieldsValidation,
6} from 'zaions-tool-kit';
7
8// Validate email
9validateEmail('user@example.com'); // true
10
11// Validate phone number
12validatePhoneNumber('+923001234567'); // true
13
14// Validate URL
15validateURL('https://example.com'); // true
16
17// Access validation rules
18const titleRules = fieldsValidation.generic.title;
19console.log(titleRules.min.val); // 1
20console.log(titleRules.max.val); // 100

See Form Validation Documentation for more details.

Image Processing

Utilities for working with images:

1import {
2  getImageDimensions,
3  getImageAspectRatio,
4  imageTypeAllowed,
5  imageUrlToBase64,
6  getImageBase64Url,
7  validateFileBeforeUpload,
8  allowedImageTypes,
9} from 'zaions-tool-kit';
10
11// Check if image type is allowed
12imageTypeAllowed('image/jpeg'); // true
13
14// Get image dimensions from a File object
15getImageDimensions(imageFile).then((dimensions) => {
16  console.log(dimensions.width, dimensions.height);
17});
18
19// Convert image URL to base64
20imageUrlToBase64('https://example.com/image.jpg').then((base64) => {
21  console.log(base64); // data:image/jpeg;base64,...
22});
23
24// Validate file before upload
25validateFileBeforeUpload({
26  file: imageFile,
27  maxSizeInMB: 2,
28  allowedTypes: allowedImageTypes,
29}).then((result) => {
30  if (result.isValid) {
31    // File is valid
32  } else {
33    console.error(result.errorMessage);
34  }
35});

See Image Processing Documentation for more details.

Firebase Utilities

ZTK includes utilities for working with Firebase:

1import {
2  frbCollectionQueryDefaults,
3  getDateFromFrbTimestamp,
4  convertToDateTimestampToStoreInDB,
5  FrbOrderbyDirectionEnum,
6  FrbWhereConditionEnum,
7  DBColumnKeysShortFormEnum,
8} from 'zaions-tool-kit';
9
10// Default query parameters
11const defaults = frbCollectionQueryDefaults;
12console.log(defaults.limit); // 10
13
14// Convert JavaScript Date to Firebase timestamp
15const timestamp = convertToDateTimestampToStoreInDB(new Date());
16
17// Convert Firebase timestamp to JavaScript Date
18const date = getDateFromFrbTimestamp(timestamp);
19
20// Use Firebase enums
21const orderDirection = FrbOrderbyDirectionEnum.desc;
22const whereCondition = FrbWhereConditionEnum.equalTo;

See Firebase Utilities Documentation for more details.

Specialized Modules

ZTK includes specialized modules for specific use cases:

Play and Win Module

1import {
2  IGame,
3  IGameRoom,
4  IUser,
5  ITransaction,
6} from 'zaions-tool-kit/play-and-win';

Roommate Module

1import {
2  ConstellationsEnum,
3  constellationsVal,
4} from 'zaions-tool-kit/roommate';

Zod Integration

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

Day.js Integration

1import { 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 :)