Quick start

This guide will help you get started with ByteKit quickly. You’ll learn how to use the core features including the API client, helper utilities, and logging.

Make sure you’ve installed ByteKit before following this guide.

Basic setup

Import ByteKit modules

Start by importing the modules you need. You can import from the main package or use modular imports:

// Import from main package
import { ApiClient, createLogger, DateUtils, StringUtils } from "bytekit";

// Or use modular imports for better tree-shaking
import { ApiClient } from "bytekit/api-client";
import { createLogger } from "bytekit/logger";
import { DateUtils } from "bytekit/date-utils";
import { StringUtils } from "bytekit/string-utils";

Create an API client

Set up an API client with your base URL and configuration:

const api = new ApiClient({
  baseUrl: "https://api.example.com",
  defaultHeaders: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
  },
  locale: "en", // or "es" for Spanish
  timeoutMs: 30000, // 30 second timeout
});

The API client automatically handles JSON serialization, retries, and error handling for you.

Make your first request

Use the API client to fetch data:

// Define your response type
interface User {
  id: number;
  name: string;
  email: string;
}

// GET request with type safety
const users = await api.get<User[]>("/users");
console.log("Users:", users);

// POST request with body
const newUser = await api.post<User>("/users", {
  body: {
    name: "John Doe",
    email: "john@example.com"
  }
});
console.log("Created user:", newUser);

// PUT request to update
const updated = await api.put<User>(`/users/${newUser.id}`, {
  body: {
    name: "Jane Doe",
    email: "jane@example.com"
  }
});

// DELETE request
await api.delete(`/users/${newUser.id}`);

Use helper utilities

ByteKit includes many helper utilities for common tasks:

// String utilities
const slug = StringUtils.slugify("Hello World! 🌍");
console.log(slug); // Output: hello-world

const camelCase = StringUtils.toCamelCase("hello_world_example");
console.log(camelCase); // Output: helloWorldExample

const masked = StringUtils.mask("1234567890", { start: 4, end: 2 });
console.log(masked); // Output: 1234****90

// Date utilities
const formatted = DateUtils.format(new Date(), "en-US");
console.log(formatted); // Output: 3/4/2026

const parsed = DateUtils.parse("2026-03-04");
console.log(parsed); // Output: Date object

const isValid = DateUtils.isValid("2026-03-04");
console.log(isValid); // Output: true

Complete example

Here’s a complete example that ties everything together:

import {
  ApiClient,
  createLogger,
  StringUtils,
  DateUtils,
  ArrayUtils,
  ObjectUtils
} from "bytekit";

// Create a logger
const logger = createLogger({
  namespace: "my-app",
  level: "info"
});

// Create an API client
const api = new ApiClient({
  baseUrl: "https://jsonplaceholder.typicode.com",
  defaultHeaders: {
    "Content-Type": "application/json"
  },
  retryPolicy: {
    maxAttempts: 3,
    initialDelayMs: 1000
  }
});

// Define types
interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

interface User {
  id: number;
  name: string;
  email: string;
}

async function main() {
  logger.info("Starting application");

  try {
    // Fetch posts
    const posts = await api.get<Post[]>("/posts", {
      searchParams: {
        _limit: 10 // Limit to 10 posts
      }
    });

    logger.info("Fetched posts", { count: posts.length });

    // Process posts with helper utilities
    const processedPosts = posts.map(post => ({
      ...post,
      slug: StringUtils.slugify(post.title),
      preview: StringUtils.truncate(post.body, 50),
      createdAt: DateUtils.format(new Date())
    }));

    // Group posts by user
    const postsByUser = ObjectUtils.groupBy(processedPosts, "userId");

    // Fetch users for unique user IDs
    const userIds = ArrayUtils.unique(posts.map(p => p.userId));
    const users = await Promise.all(
      userIds.map(id => api.get<User>(`/users/${id}`))
    );

    logger.info("Fetched users", { count: users.length });

    // Create a report
    const report = users.map(user => ({
      user: ObjectUtils.pick(user, ["id", "name", "email"]),
      postCount: postsByUser[user.id]?.length || 0,
      posts: postsByUser[user.id] || []
    }));

    logger.info("Generated report", { users: report.length });
    console.log(JSON.stringify(report, null, 2));

  } catch (error) {
    logger.error("Application error", { error });
    throw error;
  }
}

// Run the application
main().catch(console.error);

This example demonstrates:

Making HTTP requests with the API client
Using string utilities (slugify, truncate)
Using date formatting
Using array utilities (unique)
Using object utilities (groupBy, pick)
Structured logging

Advanced API client features

The API client includes powerful features for production applications:

Retry policy and circuit breaker

const api = new ApiClient({
  baseUrl: "https://api.example.com",
  
  // Retry configuration
  retryPolicy: {
    maxAttempts: 3,           // Retry up to 3 times
    initialDelayMs: 1000,     // Start with 1 second delay
    maxDelayMs: 10000,        // Max 10 seconds between retries
    factor: 2,                // Exponential backoff factor
    retryableStatusCodes: [408, 429, 500, 502, 503, 504]
  },

  // Circuit breaker configuration
  circuitBreaker: {
    failureThreshold: 5,      // Open after 5 failures
    resetTimeoutMs: 60000,    // Try again after 1 minute
    halfOpenMaxAttempts: 2    // Allow 2 test requests
  }
});

Localized error messages

const api = new ApiClient({
  baseUrl: "https://api.example.com",
  locale: "es", // Use Spanish error messages
  errorMessages: {
    es: {
      404: "Recurso no encontrado",
      500: "Error interno del servidor",
      418: "Soy una tetera ☕"
    },
    en: {
      404: "Resource not found",
      500: "Internal server error"
    }
  }
});

Request interceptors

const api = new ApiClient({
  baseUrl: "https://api.example.com",
  interceptors: {
    // Modify requests before they're sent
    request: async (url, init) => {
      // Add authentication token
      const token = await getAuthToken();
      init.headers = {
        ...init.headers,
        Authorization: `Bearer ${token}`
      };
      return [url, init];
    },
    
    // Modify responses before they're returned
    response: async (response) => {
      // Log response times
      console.log(`Request to ${response.url} took ${Date.now()}ms`);
      return response;
    }
  }
});

Using array and object utilities

ByteKit provides powerful utilities for working with arrays and objects:

import { ArrayUtils, ObjectUtils } from "bytekit";

// Array utilities
const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const chunks = ArrayUtils.chunk(numbers, 3);
// Output: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

const duplicates = [1, 2, 2, 3, 3, 3, 4];
const unique = ArrayUtils.unique(duplicates);
// Output: [1, 2, 3, 4]

const shuffled = ArrayUtils.shuffle([1, 2, 3, 4, 5]);
// Output: [3, 1, 5, 2, 4] (random order)

// Object utilities
const user = {
  id: 1,
  name: "John",
  email: "john@example.com",
  password: "secret",
  role: "admin"
};

const safe = ObjectUtils.pick(user, ["id", "name", "email"]);
// Output: { id: 1, name: "John", email: "john@example.com" }

const public = ObjectUtils.omit(user, ["password"]);
// Output: { id: 1, name: "John", email: "john@example.com", role: "admin" }

const users = [
  { id: 1, name: "John", department: "Engineering" },
  { id: 2, name: "Jane", department: "Engineering" },
  { id: 3, name: "Bob", department: "Sales" }
];

const grouped = ObjectUtils.groupBy(users, "department");
// Output:
// {
//   Engineering: [{ id: 1, ... }, { id: 2, ... }],
//   Sales: [{ id: 3, ... }]
// }

Framework integration examples

React example

import { ApiClient } from "bytekit";
import { useState, useEffect } from "react";

const api = new ApiClient({ baseUrl: "https://api.example.com" });

function UsersList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    api.get("/users")
      .then(setUsers)
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Vue example

<script setup lang="ts">
import { ref, onMounted } from "vue";
import { ApiClient } from "bytekit";

const api = new ApiClient({ baseUrl: "https://api.example.com" });
const users = ref([]);
const loading = ref(true);

onMounted(async () => {
  users.value = await api.get("/users");
  loading.value = false;
});
</script>

<template>
  <div v-if="loading">Loading...</div>
  <ul v-else>
    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

Next steps

Now that you understand the basics, explore more advanced features:

API client guide

Learn advanced API client features like caching, rate limiting, and request deduplication

Helper utilities

Explore all 28+ helper modules including validators, crypto, and caching

Logging & profiling

Set up structured logging and performance monitoring

Best practices

Production-ready patterns and optimization tips

Getting Started

Core Concepts

Guides

CLI Tool

Quick start

Quick start

Basic setup

Complete example

Advanced API client features

Retry policy and circuit breaker

Localized error messages

Request interceptors

Using array and object utilities

Framework integration examples

React example

Vue example

Next steps

API client guide

Helper utilities

Logging & profiling

Best practices

Getting Started

Core Concepts

Guides

CLI Tool

​Quick start

​Basic setup

​Complete example

​Advanced API client features

​Retry policy and circuit breaker

​Localized error messages

​Request interceptors

​Using array and object utilities

​Framework integration examples

​React example

​Vue example

​Next steps

API client guide

Helper utilities

Logging & profiling

Best practices

Quick start

Basic setup

Complete example

Advanced API client features

Retry policy and circuit breaker

Localized error messages

Request interceptors

Using array and object utilities

Framework integration examples

React example

Vue example

Next steps