DOCS: README 수정 및 FRONT,BACK -> HEAD,TAIL로 변경

Author: km-kwon

README.md

@@ -7,7 +7,7 @@ Zero dependencies (**React optional**) — perfect for logs, streaming data, rol
 
 ## Features
 
-- 🔄 **CircularBuffer (Low-level)** — direction-based circular buffer primitive (FRONT/BACK)
+- 🔄 **CircularBuffer (Low-level)** — direction-based circular buffer primitive (HEAD/TAIL)
 - 📦 **BufferManager (High-level)** — convenient API (push/pop single or arrays, peek helpers, utilities)
 - ⚛️ **React Hook** — `useCircularBuffer` for automatic re-rendering in React
 - 🎯 **Type-Safe** — full TypeScript generics support
@@ -48,26 +48,26 @@ import { CircularBuffer, Direction } from "circular-queue-react";
 
 const buf = new CircularBuffer<string>(3);
 
-// Push to BACK (newest side)
-buf.push("A", Direction.BACK);
-buf.push("B", Direction.BACK);
+// Push to TAIL (newest side)
+buf.push("A", Direction.TAIL);
+buf.push("B", Direction.TAIL);
 
-// Push to FRONT (oldest side)
-buf.push("Z", Direction.FRONT);
+// Push to HEAD (oldest side)
+buf.push("Z", Direction.HEAD);
 
-console.log(buf.get(Direction.FRONT)); // "Z" (oldest)
-console.log(buf.get(Direction.BACK)); // "B" (newest)
+console.log(buf.get(Direction.HEAD)); // "Z" (oldest)
+console.log(buf.get(Direction.TAIL)); // "B" (newest)
 
 // Peek many
-console.log(buf.get(Direction.FRONT, 2)); // ["Z","A"] (oldest -> newer)
-console.log(buf.get(Direction.BACK, 2)); // ["B","A"] (newest -> older)
+console.log(buf.get(Direction.HEAD, 2)); // ["Z","A"] (oldest -> newer)
+console.log(buf.get(Direction.TAIL, 2)); // ["B","A"] (newest -> older)
 
 // Iterate (oldest -> newest)
 for (const x of buf) console.log(x);
 
 // Pop
-console.log(buf.pop(Direction.FRONT)); // removes oldest ("Z")
-console.log(buf.pop(Direction.BACK)); // removes newest ("B")
+console.log(buf.pop(Direction.HEAD)); // removes oldest ("Z")
+console.log(buf.pop(Direction.TAIL)); // removes newest ("B")
 
 // Resize (logical capacity)
 buf.resize(10);
@@ -90,11 +90,11 @@ import { BufferManager } from "circular-queue-react";
 
 const b = new BufferManager<string>(3);
 
-// pushTail keeps newest at the end (BACK)
+// pushTail keeps newest at the end (TAIL)
 b.pushTail(["A", "B", "C", "D"]);
 console.log(b.getAll()); // ["B","C","D"] (keeps last 3)
 
-// pushHead inserts at FRONT, preserves input order
+// pushHead inserts at HEAD, preserves input order
 b.pushHead(["X", "Y"]);
 console.log(b.getAll()); // ["X","Y","B"] (oldest -> newest)
 
@@ -124,7 +124,7 @@ buf.pushTail([1, 2, 3, 4]); // keeps [2,3,4]
 
 ### 4) React Hook
 
-`useCircularBuffer` provides a BufferManager-backed stateful hook:
+`useCircularBuffer` provides a BufferManager-TAILed stateful hook:
 
 - data auto-updates after mutations
 - `pushHead` / `pushTail` / `popHead` / `popTail` / `replaceAll` / `clear` / `resize`
@@ -178,13 +178,72 @@ This library uses consistent ordering rules:
 
 ---
 
+## Important Type Limitation
+
+**⚠️ When `T` itself is an array type, the array overload for `pushHead`/`pushTail` cannot be used.**
+
+### Why?
+
+TypeScript cannot distinguish between:
+- `T` (when `T = number[]`)
+- `readonly T[]` (which would be `readonly number[][]`)
+
+Both resolve to array types, making overload resolution ambiguous.
+
+### Example
+
+```ts
+// ❌ PROBLEMATIC: T = number[]
+const buf = new BufferManager<number[]>(5);
+
+// This will fail! TypeScript cannot tell if you mean:
+// 1. Push a single item (which happens to be an array): number[]
+// 2. Push multiple items: readonly number[][]
+buf.pushTail([[1, 2], [3, 4]]);
+
+// ✅ SOLUTION: Push one item at a time
+buf.pushTail([1, 2]);     // Push single array
+buf.pushTail([3, 4]);     // Push another single array
+```
+
+### Workaround
+
+When `T` is an array type, **always push items one at a time** instead of using the array overload:
+
+```ts
+const items: number[][] = [[1, 2], [3, 4], [5, 6]];
+
+// ❌ Don't do this:
+// buf.pushTail(items);
+
+// ✅ Do this instead:
+for (const item of items) {
+  buf.pushTail(item);
+}
+
+// Or use a wrapper type:
+type Item = { data: number[] };
+const typedBuf = new BufferManager<Item>(5);
+typedBuf.pushTail([
+  { data: [1, 2] },
+  { data: [3, 4] }
+]); // ✅ Works!
+```
+
+This limitation applies to:
+- `BufferManager.pushHead()`
+- `BufferManager.pushTail()`
+- `useCircularBuffer` hook's `pushHead` and `pushTail`
+
+---
+
 ## API Reference
 
 ### Direction
 
 ```ts
-Direction.FRONT; // head / oldest side
-Direction.BACK; // tail / newest side
+Direction.HEAD; // head / oldest side
+Direction.TAIL; // tail / newest side
 ```
 
 ### CircularBuffer`<T>`
@@ -198,7 +257,7 @@ Direction.BACK; // tail / newest side
 - `push(item: T, direction: Direction): void`
 - `pop(direction: Direction): T | undefined`
 - `get(direction: Direction): T | undefined`
-- `get(direction: Direction, count: number): T[]` FRONT count: oldest → newer, BACK count: newest → older
+- `get(direction: Direction, count: number): T[]` HEAD count: oldest → newer, TAIL count: newest → older
 
 - `clear(): void`
 - `resize(newCapacity: number): void` (logical capacity)

examples/basic-usage.ts

@@ -23,52 +23,52 @@ type LogEntry = {
 
 const logBuffer = new CircularBuffer<LogEntry>(5); // Small capacity for demo
 
-// Add some logs using push with Direction.BACK (newest side)
+// Add some logs using push with Direction.TAIL (newest side)
 logBuffer.push(
   { timestamp: Date.now(), level: "info", message: "Application started" },
-  Direction.BACK
+  Direction.TAIL
 );
 logBuffer.push(
   { timestamp: Date.now(), level: "info", message: "Loading configuration" },
-  Direction.BACK
+  Direction.TAIL
 );
 logBuffer.push(
   { timestamp: Date.now(), level: "warn", message: "Cache is full" },
-  Direction.BACK
+  Direction.TAIL
 );
 logBuffer.push(
   { timestamp: Date.now(), level: "error", message: "Connection failed" },
-  Direction.BACK
+  Direction.TAIL
 );
 
 console.log("Total logs:", logBuffer.getSize());
-console.log("Oldest (FRONT):", logBuffer.get(Direction.FRONT));
-console.log("Newest (BACK):", logBuffer.get(Direction.BACK));
+console.log("Oldest (HEAD):", logBuffer.get(Direction.HEAD));
+console.log("Newest (TAIL):", logBuffer.get(Direction.TAIL));
 
 // Peek multiple without removing
 console.log(
-  "Peek newest 2 (BACK, newest->older):",
-  logBuffer.get(Direction.BACK, 2)
+  "Peek newest 2 (TAIL, newest->older):",
+  logBuffer.get(Direction.TAIL, 2)
 );
 
 // Add more logs (will overflow)
 logBuffer.push(
   { timestamp: Date.now(), level: "info", message: "Retrying connection" },
-  Direction.BACK
+  Direction.TAIL
 );
 logBuffer.push(
   { timestamp: Date.now(), level: "info", message: "Connection successful" },
-  Direction.BACK
+  Direction.TAIL
 );
 
 console.log("\nAfter overflow:");
 console.log("Total logs (still 5):", logBuffer.getSize());
-console.log("Oldest (FRONT):", logBuffer.get(Direction.FRONT));
+console.log("Oldest (HEAD):", logBuffer.get(Direction.HEAD));
 console.log("All logs (oldest->newest):", Array.from(logBuffer));
 
 // Remove one item using pop
-const removed = logBuffer.pop(Direction.FRONT);
-console.log("\nRemoved from FRONT:", removed);
+const removed = logBuffer.pop(Direction.HEAD);
+console.log("\nRemoved from HEAD:", removed);
 console.log("Size after pop:", logBuffer.getSize());
 
 // ============================================================================
@@ -80,14 +80,14 @@ console.log("==========================================");
 
 const messageBuffer = new BufferManager<string>(10);
 
-// Add to tail (BACK)
+// Add to tail (TAIL)
 messageBuffer.pushTail("Message 1");
 messageBuffer.pushTail("Message 2");
 messageBuffer.pushTail("Message 3");
 
 console.log("Messages:", messageBuffer.getAll());
 
-// Add to head (FRONT)
+// Add to head (HEAD)
 messageBuffer.pushHead("Priority Message!");
 console.log("After adding to head:", messageBuffer.getAll());
 

package-lock.json

@@ -6,7 +6,7 @@ import { Direction, type IBuffer } from "../types";
  *
  * Provides:
  * - Convenient APIs for pushing/popping single items or arrays
- * - Direction-specific helpers (head/front vs tail/back)
+ * - Direction-specific helpers (head/HEAD vs tail/TAIL)
  * - Iterable utilities (forEach/map/filter)
  *
  * Great for:
@@ -33,7 +33,7 @@ export class BufferManager<T> implements IBuffer<T> {
   // ============================================================================
 
   /**
-   * Push item(s) to the head (FRONT / oldest side).
+   * Push item(s) to the head (HEAD / oldest side).
    *
    * When pushing an array, the original order is preserved:
    * `pushHead([a,b,c])` results in `a` being the oldest among the inserted items.
@@ -45,7 +45,7 @@ export class BufferManager<T> implements IBuffer<T> {
   pushHead(input: readonly T[]): void;
   pushHead(input: T | readonly T[]): void {
     if (!this.isMany(input)) {
-      this.buffer.push(input, Direction.FRONT);
+      this.buffer.push(input, Direction.HEAD);
       return;
     }
 
@@ -54,12 +54,12 @@ export class BufferManager<T> implements IBuffer<T> {
       input.length > capacity ? input.slice(0, capacity) : input;
 
     for (let i = itemsToAdd.length - 1; i >= 0; i--) {
-      this.buffer.push(itemsToAdd[i], Direction.FRONT);
+      this.buffer.push(itemsToAdd[i], Direction.HEAD);
     }
   }
 
   /**
-   * Push item(s) to the tail (BACK / newest side).
+   * Push item(s) to the tail (TAIL / newest side).
    *
    * Optimization:
    * - If input array length exceeds logical capacity, only the last `capacity` items are processed.
@@ -68,15 +68,15 @@ export class BufferManager<T> implements IBuffer<T> {
   pushTail(input: readonly T[]): void;
   pushTail(input: T | readonly T[]): void {
     if (!this.isMany(input)) {
-      this.buffer.push(input, Direction.BACK);
+      this.buffer.push(input, Direction.TAIL);
       return;
     }
 
     const capacity = this.buffer.getLogicalCapacity();
     const itemsToAdd = input.length > capacity ? input.slice(-capacity) : input;
 
     for (const item of itemsToAdd) {
-      this.buffer.push(item, Direction.BACK);
+      this.buffer.push(item, Direction.TAIL);
     }
   }
 
@@ -94,7 +94,7 @@ export class BufferManager<T> implements IBuffer<T> {
   popHead(count: number): T[];
   popHead(count?: number): T | undefined | T[] {
     if (count === undefined) {
-      return this.buffer.pop(Direction.FRONT);
+      return this.buffer.pop(Direction.HEAD);
     }
 
     const n = Math.min(Math.max(0, Math.floor(count)), this.size());
@@ -103,7 +103,7 @@ export class BufferManager<T> implements IBuffer<T> {
     const result = new Array<T>(n);
     for (let i = 0; i < n; i++) {
       // safe because n <= size()
-      result[i] = this.buffer.pop(Direction.FRONT) as T;
+      result[i] = this.buffer.pop(Direction.HEAD) as T;
     }
     return result;
   }
@@ -118,15 +118,15 @@ export class BufferManager<T> implements IBuffer<T> {
   popTail(count: number): T[];
   popTail(count?: number): T | undefined | T[] {
     if (count === undefined) {
-      return this.buffer.pop(Direction.BACK);
+      return this.buffer.pop(Direction.TAIL);
     }
 
     const n = Math.min(Math.max(0, Math.floor(count)), this.size());
     if (n === 0) return [];
 
     const result = new Array<T>(n);
     for (let i = 0; i < n; i++) {
-      result[i] = this.buffer.pop(Direction.BACK) as T;
+      result[i] = this.buffer.pop(Direction.TAIL) as T;
     }
     return result;
   }
@@ -145,8 +145,8 @@ export class BufferManager<T> implements IBuffer<T> {
   getHead(count: number): T[];
   getHead(count?: number): T | undefined | T[] {
     return count === undefined
-      ? this.buffer.get(Direction.FRONT)
-      : this.buffer.get(Direction.FRONT, count);
+      ? this.buffer.get(Direction.HEAD)
+      : this.buffer.get(Direction.HEAD, count);
   }
 
   /**
@@ -159,8 +159,8 @@ export class BufferManager<T> implements IBuffer<T> {
   getTail(count: number): T[];
   getTail(count?: number): T | undefined | T[] {
     return count === undefined
-      ? this.buffer.get(Direction.BACK)
-      : this.buffer.get(Direction.BACK, count);
+      ? this.buffer.get(Direction.TAIL)
+      : this.buffer.get(Direction.TAIL, count);
   }
 
   /**