@codeleap/debug 5.8.8

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@codeleap/debug",
+  "version": "5.8.8",
+  "main": "src/index.ts",
+  "license": "UNLICENSED",
+  "repository": {
+    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
+    "type": "git",
+    "directory": "packages/debug"
+  },
+  "devDependencies": {
+    "@codeleap/config": "5.8.8",
+    "ts-node-dev": "1.1.8"
+  },
+  "scripts": {
+    "build": "echo 'No build needed'"
+  },
+  "peerDependencies": {
+    "typescript": "5.5.2"
+  }
+}

package/package.json.bak

@@ -0,0 +1,21 @@
+{
+  "name": "@codeleap/debug",
+  "version": "5.8.8",
+  "main": "src/index.ts",
+  "license": "UNLICENSED",
+  "repository": {
+    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
+    "type": "git",
+    "directory": "packages/debug"
+  },
+  "devDependencies": {
+    "@codeleap/config": "workspace:*",
+    "ts-node-dev": "1.1.8"
+  },
+  "scripts": {
+    "build": "echo 'No build needed'"
+  },
+  "peerDependencies": {
+    "typescript": "5.5.2"
+  }
+}

package/src/FakeRestApi/class.ts

@@ -0,0 +1,243 @@
+import { FakeItem, FakeRestApiOptions, PaginationResponse } from './types'
+
+/**
+ * A fake REST API implementation for testing and prototyping.
+ * Provides CRUD operations with pagination support and optional request delays.
+ * @template T - The type of items to manage, must extend FakeItem
+ * @template F - The type of filters to apply when listing items
+ */
+export class FakeRestApi<T extends FakeItem, F = Record<string, unknown>> {
+  private data: T[] = []
+  private options: Required<FakeRestApiOptions<T, F>>
+
+  /**
+   * Gets the ID of the last item in the data array.
+   * @private
+   * @returns The highest ID or 0 if no items exist
+   */
+  private get lastId(): T['id'] {
+    return this.data.length > 0 ? Math.max(...this.data.map((i) => i.id)) : 0
+  }
+
+  /**
+   * Gets the name of the API.
+   * @returns The API name
+   */
+  public get name(): string {
+    return this.options.name
+  }
+
+  /**
+   * Gets the current count of items.
+   * @returns The number of items in the data array
+   */
+  public get count(): number {
+    return this.data.length
+  }
+
+  /**
+   * Creates a new FakeRestApi instance.
+   * @param options - Configuration options for the API
+   */
+  constructor(options: FakeRestApiOptions<T, F>) {
+    this.options = {
+      delayMs: 2500,
+      maxCount: 100,
+      enableDelay: false,
+      filterFn: () => true,
+      ...options,
+    }
+
+    this.initialize()
+  }
+
+  /**
+   * Initializes the data array with items up to maxCount.
+   * @private
+   */
+  private initialize(): void {
+    this.data = Array.from({ length: this.options.maxCount }, (_, i) =>
+      this.generateItem(i + 1)
+    )
+  }
+
+  /**
+   * Updates the API options partially.
+   * @param newOptions - Partial options to update
+   */
+  public setOptions(newOptions: Partial<FakeRestApiOptions<T, F>>): void {
+    this.options = { ...this.options, ...newOptions }
+  }
+
+  /**
+   * Generates a new item using the generator function.
+   * @param id - The ID for the new item (defaults to lastId + 1)
+   * @returns A newly generated item
+   */
+  public generateItem(id: T['id'] = this.lastId + 1): T {
+    return this.options.generatorFn(id)
+  }
+
+  /**
+   * Introduces an artificial delay if enabled in options.
+   * @private
+   * @returns A promise that resolves after the delay period
+   */
+  private async delay(): Promise<void> {
+    if (!this.options.enableDelay) return
+
+    return new Promise((resolve) => {
+      setTimeout(resolve, this.options.delayMs)
+    })
+  }
+
+  /**
+   * Builds a URL with pagination parameters.
+   * @private
+   * @param limit - Number of items per page
+   * @param offset - Starting position
+   * @returns A formatted URL string
+   */
+  private buildUrl(limit: number, offset: number): string {
+    return `https://api.${this.name}?limit=${limit}&offset=${offset}`
+  }
+
+  /**
+   * Retrieves a paginated list of items with optional filtering.
+   * @param limit - Number of items to return (default: 10)
+   * @param offset - Starting position (default: 0)
+   * @param filters - Optional filters to apply
+   * @returns A promise that resolves to a paginated response
+   */
+  async listItems(
+    limit = 10,
+    offset = 0,
+    filters?: F
+  ): Promise<PaginationResponse<T>> {
+    await this.delay()
+
+    const hasFilters = filters && Object.keys(filters).length > 0
+    const items = hasFilters
+      ? this.data.filter((item) => this.options.filterFn(item, filters))
+      : this.data
+
+    const total = items.length
+    const start = Math.max(0, offset)
+    const end = Math.min(start + limit, total)
+
+    const results = items.slice(start, end)
+
+    return {
+      count: total,
+      next: end < total ? this.buildUrl(limit, end) : null,
+      previous: start > 0 ? this.buildUrl(limit, Math.max(0, start - limit)) : null,
+      results,
+    }
+  }
+
+  /**
+   * Retrieves a single item by ID.
+   * @param id - The ID of the item to retrieve
+   * @returns A promise that resolves to the requested item
+   * @throws {Error} If the item is not found
+   */
+  async retrieveItem(id: T['id']): Promise<T> {
+    await this.delay()
+
+    const item = this.data.find((i) => i.id === id)
+
+    if (!item) {
+      throw new Error(`${this.name} with id ${id} not found`)
+    }
+
+    return item
+  }
+
+  /**
+   * Creates a new item and adds it to the data array.
+   * @param item - Optional partial item data (ID will be auto-generated)
+   * @returns A promise that resolves to the created item
+   */
+  async createItem(item?: Partial<T>): Promise<T> {
+    await this.delay()
+
+    const id = this.lastId + 1
+    const newItem = item ? { ...item, id } as T : this.generateItem(id)
+
+    this.data.push(newItem)
+
+    return newItem
+  }
+
+  /**
+   * Updates an existing item by ID.
+   * @param id - The ID of the item to update
+   * @param updates - Partial item data to update
+   * @returns A promise that resolves to the updated item
+   * @throws {Error} If the item is not found
+   */
+  async updateItem(id: T['id'], updates: Partial<T>): Promise<T> {
+    await this.delay()
+
+    const index = this.data.findIndex((i) => i.id === id)
+
+    if (index === -1) {
+      throw new Error(`${this.name} with id ${id} not found`)
+    }
+
+    this.data[index] = { ...this.data[index], ...updates, id }
+
+    return this.data[index]
+  }
+
+  /**
+   * Deletes an item by ID.
+   * @param id - The ID of the item to delete
+   * @returns A promise that resolves to the deleted item
+   * @throws {Error} If the item is not found
+   */
+  async deleteItem(id: T['id']): Promise<T> {
+    await this.delay()
+
+    const index = this.data.findIndex((i) => i.id === id)
+
+    if (index === -1) {
+      throw new Error(`${this.name} with id ${id} not found`)
+    }
+
+    const [deleted] = this.data.splice(index, 1)
+
+    return deleted
+  }
+
+  /**
+   * Resets the data array to its initial state by regenerating all items.
+   */
+  public reset(): void {
+    this.initialize()
+  }
+
+  /**
+   * Clears all items from the data array.
+   */
+  public clear(): void {
+    this.data = []
+  }
+
+  /**
+   * Gets a readonly copy of all items in the data array.
+   * @returns A frozen array of all items
+   */
+  public getData(): readonly T[] {
+    return Object.freeze([...this.data])
+  }
+
+  /**
+   * Gets a single item by ID without delay.
+   * @param id - The ID of the item to retrieve
+   * @returns The item if found, undefined otherwise
+   */
+  public getItem(id: T['id']): T | undefined {
+    return this.data.find((i) => i.id === id)
+  }
+}

package/src/FakeRestApi/factor.ts

@@ -0,0 +1,29 @@
+import { FakeRestApi } from './class'
+import { FakeItem, FakeRestApiOptions } from './types'
+
+/**
+ * Factory function to create a new FakeRestApi instance.
+ * @template T - The type of items to manage, must extend FakeItem
+ * @template F - The type of filters to apply when listing items
+ * @param options - Configuration options for the API
+ * @returns A new FakeRestApi instance
+ * @example
+ * ```typescript
+ * type User = { id: number; name: string; email: string }
+ * 
+ * const api = createFakeRestApi<User>({
+ *   name: 'users',
+ *   maxCount: 50,
+ *   generatorFn: (id) => ({
+ *     id,
+ *     name: `User ${id}`,
+ *     email: `user${id}@example.com`
+ *   })
+ * })
+ * ```
+ */
+export function createFakeRestApi<T extends FakeItem, F = Record<string, unknown>>(
+  options: FakeRestApiOptions<T, F>
+): FakeRestApi<T, F> {
+  return new FakeRestApi<T, F>(options)
+}

package/src/FakeRestApi/index.ts

@@ -0,0 +1,3 @@
+export * from './factor'
+export * from './class'
+export type { FakeRestApiOptions } from './types'

package/src/FakeRestApi/tests.spec.ts

@@ -0,0 +1,368 @@
+import { describe, test, expect, beforeEach } from 'bun:test'
+import { FakeRestApi } from './class'
+import { createFakeRestApi } from './factor'
+
+type User = {
+  id: number
+  name: string
+  email: string
+  age: number
+  active: boolean
+}
+
+type UserFilters = {
+  name?: string
+  minAge?: number
+  active?: boolean
+}
+
+describe('FakeRestApi', () => {
+  let api: FakeRestApi<User, UserFilters>
+
+  beforeEach(() => {
+    api = createFakeRestApi<User, UserFilters>({
+      name: 'users',
+      enableDelay: false,
+      maxCount: 20,
+      generatorFn: (id) => ({
+        id,
+        name: `User ${id}`,
+        email: `user${id}@example.com`,
+        age: 20 + id,
+        active: id % 2 === 0,
+      }),
+      filterFn: (item, filters) => {
+        if (filters.name && !item.name.toLowerCase().includes(filters.name.toLowerCase())) {
+          return false
+        }
+
+        if (filters.minAge !== undefined && item.age < filters.minAge) {
+          return false
+        }
+
+        if (filters.active !== undefined && item.active !== filters.active) {
+          return false
+        }
+
+        return true
+      },
+    })
+  })
+
+  describe('Constructor', () => {
+    test('should create the API with default settings', () => {
+      expect(api.name).toBe('users')
+      expect(api.count).toBe(20)
+    })
+
+    test('should automatically generate initial items', () => {
+      const data = api.getData()
+      expect(data).toHaveLength(20)
+      expect(data[0].id).toBe(1)
+      expect(data[0].name).toBe('User 1')
+    })
+  })
+
+  describe('listItems', () => {
+    test('should list items with default pagination', async () => {
+      const result = await api.listItems()
+
+      expect(result.count).toBe(20)
+      expect(result.results).toHaveLength(10)
+      expect(result.next).toBe('https://api.users?limit=10&offset=10')
+      expect(result.previous).toBeNull()
+    })
+
+    test('should respect limit and offset', async () => {
+      const result = await api.listItems(5, 10)
+
+      expect(result.results).toHaveLength(5)
+      expect(result.results[0].id).toBe(11)
+      expect(result.next).toBe('https://api.users?limit=5&offset=15')
+      expect(result.previous).toBe('https://api.users?limit=5&offset=5')
+    })
+
+    test('should return null for next when there are no more items', async () => {
+      const result = await api.listItems(10, 15)
+
+      expect(result.results).toHaveLength(5)
+      expect(result.next).toBeNull()
+    })
+
+    test('should return null for previous when offset is 0', async () => {
+      const result = await api.listItems(10, 0)
+
+      expect(result.previous).toBeNull()
+    })
+
+    test('should filter by name', async () => {
+      const result = await api.listItems(20, 0, { name: 'User 1' })
+
+      expect(result.count).toBe(11)
+      expect(result.results.every(u => u.name.includes('User 1'))).toBe(true)
+    })
+
+    test('should filter by minimum age', async () => {
+      const result = await api.listItems(20, 0, { minAge: 30 })
+
+      expect(result.results.every(u => u.age >= 30)).toBe(true)
+    })
+
+    test('should filter by active status', async () => {
+      const result = await api.listItems(20, 0, { active: true })
+
+      expect(result.results.every(u => u.active === true)).toBe(true)
+    })
+
+    test('should apply multiple filters', async () => {
+      const result = await api.listItems(20, 0, { active: true, minAge: 25 })
+
+      expect(result.results.every(u => u.active === true && u.age >= 25)).toBe(true)
+    })
+
+    test('should handle negative offset', async () => {
+      const result = await api.listItems(10, -5)
+
+      expect(result.results[0].id).toBe(1)
+    })
+  })
+
+  describe('retrieveItem', () => {
+    test('should retrieve item by id', async () => {
+      const user = await api.retrieveItem(5)
+
+      expect(user.id).toBe(5)
+      expect(user.name).toBe('User 5')
+      expect(user.email).toBe('user5@example.com')
+    })
+
+    test('should throw an error when item does not exist', async () => {
+      expect(async () => {
+        await api.retrieveItem(999)
+      }).toThrow('users with id 999 not found')
+    })
+  })
+
+  describe('createItem', () => {
+    test('should create item with provided data', async () => {
+      const newUser = await api.createItem({
+        name: 'John Smith',
+        email: 'john@example.com',
+        age: 28,
+        active: true,
+      })
+
+      expect(newUser.id).toBe(21)
+      expect(newUser.name).toBe('John Smith')
+      expect(api.count).toBe(21)
+    })
+
+    test('should generate item automatically when not provided', async () => {
+      const newUser = await api.createItem()
+
+      expect(newUser.id).toBe(21)
+      expect(newUser.name).toBe('User 21')
+      expect(api.count).toBe(21)
+    })
+
+    test('should auto-increment the id', async () => {
+      const user1 = await api.createItem()
+      const user2 = await api.createItem()
+
+      expect(user1.id).toBe(21)
+      expect(user2.id).toBe(22)
+    })
+  })
+
+  describe('updateItem', () => {
+    test('should update existing item', async () => {
+      const updated = await api.updateItem(5, {
+        name: 'User Updated',
+        age: 99,
+      })
+
+      expect(updated.id).toBe(5)
+      expect(updated.name).toBe('User Updated')
+      expect(updated.age).toBe(99)
+      expect(updated.email).toBe('user5@example.com')
+    })
+
+    test('should preserve the original id', async () => {
+      const updated = await api.updateItem(5, { id: 999 } as any)
+
+      expect(updated.id).toBe(5)
+    })
+
+    test('should throw an error when item does not exist', async () => {
+      expect(async () => {
+        await api.updateItem(999, { name: 'Test' })
+      }).toThrow('users with id 999 not found')
+    })
+  })
+
+  describe('deleteItem', () => {
+    test('should delete existing item', async () => {
+      const deleted = await api.deleteItem(5)
+
+      expect(deleted.id).toBe(5)
+      expect(api.count).toBe(19)
+      expect(api.getItem(5)).toBeUndefined()
+    })
+
+    test('should throw an error when item does not exist', async () => {
+      expect(async () => {
+        await api.deleteItem(999)
+      }).toThrow('users with id 999 not found')
+    })
+  })
+
+  describe('Utility methods', () => {
+    test('getItem should return existing item', () => {
+      const user = api.getItem(5)
+
+      expect(user).toBeDefined()
+      expect(user?.id).toBe(5)
+    })
+
+    test('getItem should return undefined for non-existing item', () => {
+      const user = api.getItem(999)
+
+      expect(user).toBeUndefined()
+    })
+
+    test('getData should return frozen array', () => {
+      const data = api.getData()
+
+      expect(data).toHaveLength(20)
+      expect(Object.isFrozen(data)).toBe(true)
+    })
+
+    test('clear should remove all items', () => {
+      api.clear()
+
+      expect(api.count).toBe(0)
+      expect(api.getData()).toHaveLength(0)
+    })
+
+    test('reset should restore initial items', () => {
+      api.clear()
+      expect(api.count).toBe(0)
+
+      api.reset()
+
+      expect(api.count).toBe(20)
+      expect(api.getData()[0].id).toBe(1)
+    })
+
+    test('generateItem should generate new item with provided id', () => {
+      const user = api.generateItem(100)
+
+      expect(user.id).toBe(100)
+      expect(user.name).toBe('User 100')
+    })
+
+    test('generateItem should use lastId + 1 when not provided', () => {
+      const user = api.generateItem()
+
+      expect(user.id).toBe(21)
+    })
+  })
+
+  describe('setOptions', () => {
+    test('should update options', () => {
+      api.setOptions({ enableDelay: true, delayMs: 5000 })
+
+      expect(api.name).toBe('users')
+    })
+  })
+
+  describe('Delay', () => {
+    test('should respect delay when enabled', async () => {
+      const apiWithDelay = createFakeRestApi<User>({
+        name: 'delayed',
+        enableDelay: true,
+        delayMs: 100,
+        maxCount: 5,
+        generatorFn: (id) => ({
+          id,
+          name: `User ${id}`,
+          email: `user${id}@example.com`,
+          age: 20,
+          active: true,
+        }),
+      })
+
+      const start = Date.now()
+      await apiWithDelay.listItems()
+      const duration = Date.now() - start
+
+      expect(duration).toBeGreaterThanOrEqual(100)
+    })
+
+    test('should be instantaneous when delay is disabled', async () => {
+      const start = Date.now()
+      await api.listItems()
+      const duration = Date.now() - start
+
+      expect(duration).toBeLessThan(50)
+    })
+  })
+
+  describe('Edge cases', () => {
+    test('should handle maxCount = 0', () => {
+      const emptyApi = createFakeRestApi<User>({
+        name: 'empty',
+        maxCount: 0,
+        generatorFn: (id) => ({
+          id,
+          name: `User ${id}`,
+          email: `user${id}@example.com`,
+          age: 20,
+          active: true,
+        }),
+      })
+
+      expect(emptyApi.count).toBe(0)
+    })
+
+    test('should handle empty filters', async () => {
+      const result = await api.listItems(10, 0, {})
+
+      expect(result.count).toBe(20)
+    })
+
+    test('should handle limit greater than total', async () => {
+      const result = await api.listItems(100, 0)
+
+      expect(result.results).toHaveLength(20)
+      expect(result.next).toBeNull()
+    })
+
+    test('should handle offset greater than total', async () => {
+      const result = await api.listItems(10, 100)
+
+      expect(result.results).toHaveLength(0)
+      expect(result.next).toBeNull()
+    })
+  })
+
+  describe('API without filterFn', () => {
+    test('should work without filterFn defined', async () => {
+      const simpleApi = createFakeRestApi<User>({
+        name: 'simple',
+        maxCount: 10,
+        generatorFn: (id) => ({
+          id,
+          name: `User ${id}`,
+          email: `user${id}@example.com`,
+          age: 20,
+          active: true,
+        }),
+      })
+
+      const result = await simpleApi.listItems(5, 0, { name: 'test' })
+
+      expect(result.count).toBe(10)
+    })
+  })
+})

package/src/FakeRestApi/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Represents a basic item with an ID.
+ */
+export type FakeItem = {
+  id: number
+}
+
+/**
+ * Represents a paginated response structure.
+ * @template T - The type of items in the results array, must extend FakeItem
+ */
+export type PaginationResponse<T extends FakeItem> = {
+  /** Total count of items */
+  count: number
+  /** URL for the next page, or null if there are no more pages */
+  next: string | null
+  /** URL for the previous page, or null if this is the first page */
+  previous: string | null
+  /** Array of items for the current page */
+  results: T[]
+}
+
+/**
+ * Configuration options for creating a FakeRestApi instance.
+ * @template T - The type of items to manage, must extend FakeItem
+ * @template F - The type of filters to apply when listing items
+ */
+export type FakeRestApiOptions<T extends FakeItem, F = Record<string, unknown>> = {
+  /** Name of the API (used in URLs and error messages) */
+  name: string
+  /** Whether to enable artificial delay for requests */
+  enableDelay?: boolean
+  /** Maximum number of items to generate on initialization */
+  maxCount?: number
+  /** Delay duration in milliseconds */
+  delayMs?: number
+  /** Function to generate a new item given an ID */
+  generatorFn: (id: T['id']) => T
+  /** Optional function to filter items based on criteria */
+  filterFn?: (item: T, filters: F) => boolean
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './FakeRestApi'