@zipbul/result 0.0.1

package/README.ko.md

@@ -0,0 +1,383 @@
+# @zipbul/result
+
+[English](./README.md) | **한국어**
+
+예외(exception) 없이 에러를 처리하는 경량 Result 타입입니다.
+클래스로 감싸지 않고 평범한 유니온 값(`T | Err<E>`)을 반환합니다 — 런타임 오버헤드 제로, 완전한 타입 안전성.
+
+> throw 없음, try/catch 없음, 래퍼 클래스 없음. 값만 있습니다.
+
+<br>
+
+## 📦 설치
+
+```bash
+bun add @zipbul/result
+```
+
+<br>
+
+## 💡 핵심 개념
+
+`throw`를 사용하는 전통적 에러 처리는 제어 흐름을 끊고, 타입 정보를 잃으며, 호출자에게 `try/catch` 추측 게임을 강요합니다.
+
+```typescript
+// ❌ Throw — 호출자는 뭐가 올지 전혀 모릅니다
+function parseConfig(raw: string): Config {
+  if (!raw) throw new Error('empty input');      // 타입이 뭔가요? 알 수 없음.
+  if (!valid(raw)) throw new ValidationError();  // 조용히 상위로 전파됨.
+  return JSON.parse(raw);
+}
+
+try {
+  const config = parseConfig(input);
+} catch (e) {
+  // `e`가 뭔가요? Error? ValidationError? JSON.parse의 SyntaxError?
+  // TypeScript는 여기서 도와줄 수 없습니다 — `e`는 `unknown`입니다.
+}
+```
+
+```typescript
+// ✅ Result — 타입 안전, 명시적, 놀라움 없음
+import { err, isErr, type Result } from '@zipbul/result';
+
+function parseConfig(raw: string): Result<Config, string> {
+  if (!raw) return err('empty input');
+  if (!valid(raw)) return err('validation failed');
+  return JSON.parse(raw);
+}
+
+const result = parseConfig(input);
+
+if (isErr(result)) {
+  console.error(result.data); // string — TypeScript가 타입을 압니다
+} else {
+  console.log(result.host);   // Config — 완전히 좁혀짐
+}
+```
+
+<br>
+
+## 🚀 빠른 시작
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+function findUser(id: number): Result<User, string> {
+  if (id <= 0) return err('Invalid ID');
+
+  const user = db.get(id);
+  if (!user) return err('User not found');
+
+  return user;
+}
+
+const result = findUser(42);
+
+if (isErr(result)) {
+  // result는 Err<string>
+  console.error(`실패: ${result.data}`);
+} else {
+  // result는 User
+  console.log(`안녕하세요, ${result.name}`);
+}
+```
+
+<br>
+
+## 📚 API 레퍼런스
+
+### `err()`
+
+불변(immutable) `Err` 값을 생성합니다. 절대 throw하지 않습니다.
+
+```typescript
+import { err } from '@zipbul/result';
+```
+
+| 오버로드 | 반환 | 설명 |
+|:---------|:-----|:-----|
+| `err()` | `Err<never>` | 데이터 없는 에러 |
+| `err<E>(data: E)` | `Err<E>` | 데이터가 첨부된 에러 |
+
+```typescript
+// 데이터 없음 — 단순 신호
+const e1 = err();
+// e1.data → never (접근 불가)
+// e1.stack → 캡처된 스택 트레이스
+
+// 데이터 포함 — 에러 상세 정보 전달
+const e2 = err('not found');
+// e2.data → 'not found'
+// e2.stack → 캡처된 스택 트레이스
+
+// 풍부한 에러 객체
+const e3 = err({ code: 'TIMEOUT', retryAfter: 3000 });
+// e3.data.code → 'TIMEOUT'
+```
+
+반환된 `Err`의 프로퍼티:
+
+| 프로퍼티 | 타입 | 설명 |
+|:---------|:-----|:-----|
+| `data` | `E` | 첨부된 에러 데이터 |
+| `stack` | `string` | `err()` 호출 지점에서 캡처된 스택 트레이스 |
+
+> **불변성** — 모든 `Err`는 `Object.freeze()`됩니다. strict mode에서 프로퍼티를 수정하면 `TypeError`가 발생합니다.
+
+<br>
+
+### `isErr()`
+
+값을 `Err<E>`로 좁히는 타입 가드입니다.
+
+```typescript
+import { isErr } from '@zipbul/result';
+```
+
+```typescript
+function isErr<E = unknown>(value: unknown): value is Err<E>
+```
+
+- `value`가 null이 아닌 객체이고, 마커 프로퍼티가 `true`인 경우에만 `true`를 반환합니다.
+- **절대 throw하지 않습니다** — `null`, `undefined`, 원시값, 예외를 내부적으로 처리합니다.
+
+```typescript
+const result: Result<number, string> = doSomething();
+
+if (isErr(result)) {
+  // result: Err<string>
+  console.error(result.data);
+} else {
+  // result: number
+  console.log(result + 1);
+}
+```
+
+> **제네릭 `E` 주의사항** — `isErr<E>()`는 타입 단언만 제공합니다. `data`의 형태를 런타임에서 검증하지 않습니다. 호출자가 제네릭이 실제 에러 타입과 일치하는지 보장해야 합니다.
+
+<br>
+
+### `Result<T, E>`
+
+평범한 유니온 타입 — 래퍼 클래스가 아닙니다.
+
+```typescript
+type Result<T, E = never> = T | Err<E>;
+```
+
+| 파라미터 | 기본값 | 설명 |
+|:---------|:-------|:-----|
+| `T` | — | 성공 값 타입 |
+| `E` | `never` | 에러 데이터 타입 |
+
+```typescript
+// 단순 — 에러 데이터 없음
+type MayFail = Result<Config>;
+
+// 에러 데이터 포함
+type ParseResult = Result<Config, string>;
+
+// 풍부한 에러 타입
+type ApiResult = Result<User, { code: string; message: string }>;
+```
+
+<br>
+
+### `Err<E>`
+
+`err()`가 반환하는 에러 타입입니다.
+
+```typescript
+type Err<E = never> = {
+  stack: string;
+  data: E;
+};
+```
+
+> 식별에 사용되는 마커 프로퍼티는 의도적으로 타입에서 제외됩니다. `err()`가 런타임에 내부적으로 추가하고, `isErr()`를 통해서만 판별합니다 — 이렇게 하면 공개 API 표면이 깔끔해지고, 소비자가 구현 세부사항에 의존하는 것을 방지합니다.
+
+<br>
+
+### 마커 키(Marker Key)
+
+마커 키는 `Err` 객체를 식별하는 데 사용되는 숨겨진 고유 프로퍼티입니다. 충돌에 강한 문자열이 기본값입니다.
+
+```typescript
+import { DEFAULT_MARKER_KEY, getMarkerKey, setMarkerKey } from '@zipbul/result';
+```
+
+| 내보내기 | 타입 | 설명 |
+|:---------|:-----|:-----|
+| `DEFAULT_MARKER_KEY` | `string` | `'__$$e_9f4a1c7b__'` — 기본 키 |
+| `getMarkerKey()` | `() => string` | 현재 마커 키 반환 |
+| `setMarkerKey(key)` | `(key: string) => void` | 마커 키 변경 |
+
+```typescript
+// 독립 모듈 간 감지 리셋
+import { setMarkerKey, getMarkerKey } from '@zipbul/result';
+
+setMarkerKey('__my_app_err__');
+console.log(getMarkerKey()); // '__my_app_err__'
+```
+
+> **검증** — `setMarkerKey()`는 키가 빈 문자열이거나 공백만으로 이루어진 경우 `TypeError`를 던집니다.
+>
+> **주의** — 마커 키를 변경하면 `isErr()`가 이전 키로 생성된 `Err` 객체를 더 이상 인식하지 못합니다. 독립 모듈 간 에러 도메인을 분리해야 할 때만 변경하세요.
+
+<br>
+
+## 🔬 고급 사용법
+
+### Result를 반환하는 함수
+
+`Result`로 함수 시그니처를 정의하면 에러 경로가 타입 시스템에서 명시적으로 드러납니다.
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface ValidationError {
+  field: string;
+  message: string;
+}
+
+function validate(input: unknown): Result<ValidData, ValidationError> {
+  if (!input || typeof input !== 'object') {
+    return err({ field: 'root', message: 'Expected an object' });
+  }
+  // ... 검증 로직
+  return input as ValidData;
+}
+
+const result = validate(body);
+if (isErr(result)) {
+  return Response.json({ error: result.data }, { status: 400 });
+}
+// result는 여기서 ValidData
+```
+
+### 결과 체이닝
+
+`Result`는 평범한 유니온이므로 `.map()`이나 `.flatMap()`이 없습니다. 표준 제어 흐름을 사용하세요:
+
+```typescript
+function processOrder(orderId: string): Result<Receipt, string> {
+  const order = findOrder(orderId);
+  if (isErr(order)) return order; // 전파
+
+  const payment = chargePayment(order);
+  if (isErr(payment)) return payment; // 전파
+
+  return generateReceipt(order, payment);
+}
+```
+
+> 이것은 의도된 설계입니다. `.map()` / `.flatMap()`이 있는 클래스는 런타임 비용을 추가하고 특정 합성 스타일을 강요합니다. 평범한 값 + `isErr()`는 표준 `if`, `switch`, early return 등 원하는 패턴을 자유롭게 사용할 수 있게 합니다.
+
+### 비동기 결과
+
+`Promise`와 자연스럽게 작동합니다:
+
+```typescript
+async function fetchUser(id: number): Promise<Result<User, ApiError>> {
+  try {
+    const res = await fetch(`/api/users/${id}`);
+    if (!res.ok) return err({ code: res.status, message: res.statusText });
+    return await res.json();
+  } catch {
+    return err({ code: 0, message: 'Network error' });
+  }
+}
+```
+
+### 스택 트레이스
+
+모든 `Err`는 생성 시점에 스택 트레이스를 캡처하여, `throw` 없이 디버깅이 가능합니다:
+
+```typescript
+const e = err('something went wrong');
+console.log(e.stack);
+// Error
+//     at err (/.../err.ts:22:18)
+//     at validate (/.../validate.ts:15:12)
+//     at handleRequest (/.../server.ts:8:20)
+```
+
+<br>
+
+## 🔌 프레임워크 연동 예시
+
+<details>
+<summary><b>Bun.serve</b></summary>
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface AppError {
+  code: string;
+  message: string;
+}
+
+function parseBody(request: Request): Promise<Result<Payload, AppError>> {
+  // ... Result 반환
+}
+
+Bun.serve({
+  async fetch(request) {
+    const body = await parseBody(request);
+
+    if (isErr(body)) {
+      return Response.json(
+        { error: body.data.code, message: body.data.message },
+        { status: 400 },
+      );
+    }
+
+    // body는 Payload
+    return Response.json({ ok: true, data: process(body) });
+  },
+  port: 3000,
+});
+```
+
+</details>
+
+<details>
+<summary><b>@zipbul/cors와 함께</b></summary>
+
+```typescript
+import { Cors, CorsAction } from '@zipbul/cors';
+import { isErr } from '@zipbul/result';
+
+const corsResult = Cors.create({
+  origin: 'https://app.example.com',
+  credentials: true,
+});
+
+// Cors.create()는 Result<Cors, CorsError>를 반환합니다
+if (isErr(corsResult)) {
+  throw new Error(`CORS 설정 에러: ${corsResult.data.message}`);
+}
+
+const cors = corsResult;
+
+// cors.handle()는 Promise<Result<CorsResult, CorsError>>를 반환합니다
+const result = await cors.handle(request);
+
+if (isErr(result)) {
+  return new Response('Internal Error', { status: 500 });
+}
+```
+
+</details>
+
+<br>
+
+## 📄 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,383 @@
+# @zipbul/result
+
+**English** | [한국어](./README.ko.md)
+
+A lightweight Result type for error handling without exceptions.
+Returns plain union values (`T | Err<E>`) instead of wrapping in classes — zero runtime overhead, full type safety.
+
+> No throw, no try/catch, no wrapper class. Just values.
+
+<br>
+
+## 📦 Installation
+
+```bash
+bun add @zipbul/result
+```
+
+<br>
+
+## 💡 Core Concept
+
+Traditional error handling with `throw` breaks control flow, loses type information, and forces callers into a `try/catch` guessing game.
+
+```typescript
+// ❌ Throw — caller has no idea what to expect
+function parseConfig(raw: string): Config {
+  if (!raw) throw new Error('empty input');      // What type? Unknown.
+  if (!valid(raw)) throw new ValidationError();  // Silently propagates up.
+  return JSON.parse(raw);
+}
+
+try {
+  const config = parseConfig(input);
+} catch (e) {
+  // What is `e`? Error? ValidationError? SyntaxError from JSON.parse?
+  // TypeScript cannot help you here — `e` is `unknown`.
+}
+```
+
+```typescript
+// ✅ Result — type-safe, explicit, no surprises
+import { err, isErr, type Result } from '@zipbul/result';
+
+function parseConfig(raw: string): Result<Config, string> {
+  if (!raw) return err('empty input');
+  if (!valid(raw)) return err('validation failed');
+  return JSON.parse(raw);
+}
+
+const result = parseConfig(input);
+
+if (isErr(result)) {
+  console.error(result.data); // string — TypeScript knows the type
+} else {
+  console.log(result.host);   // Config — fully narrowed
+}
+```
+
+<br>
+
+## 🚀 Quick Start
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+function findUser(id: number): Result<User, string> {
+  if (id <= 0) return err('Invalid ID');
+
+  const user = db.get(id);
+  if (!user) return err('User not found');
+
+  return user;
+}
+
+const result = findUser(42);
+
+if (isErr(result)) {
+  // result is Err<string>
+  console.error(`Failed: ${result.data}`);
+} else {
+  // result is User
+  console.log(`Hello, ${result.name}`);
+}
+```
+
+<br>
+
+## 📚 API Reference
+
+### `err()`
+
+Creates an immutable `Err` value. Never throws.
+
+```typescript
+import { err } from '@zipbul/result';
+```
+
+| Overload | Return | Description |
+|:---------|:-------|:------------|
+| `err()` | `Err<never>` | Error with no data |
+| `err<E>(data: E)` | `Err<E>` | Error with attached data |
+
+```typescript
+// No data — simple signal
+const e1 = err();
+// e1.data → never (cannot access)
+// e1.stack → captured stack trace
+
+// With data — carry error details
+const e2 = err('not found');
+// e2.data → 'not found'
+// e2.stack → captured stack trace
+
+// Rich error objects
+const e3 = err({ code: 'TIMEOUT', retryAfter: 3000 });
+// e3.data.code → 'TIMEOUT'
+```
+
+Properties of the returned `Err`:
+
+| Property | Type | Description |
+|:---------|:-----|:------------|
+| `data` | `E` | The attached error data |
+| `stack` | `string` | Stack trace captured at `err()` call site |
+
+> **Immutability** — every `Err` is `Object.freeze()`d. Attempting to modify properties in strict mode throws a `TypeError`.
+
+<br>
+
+### `isErr()`
+
+Type guard that narrows a value to `Err<E>`.
+
+```typescript
+import { isErr } from '@zipbul/result';
+```
+
+```typescript
+function isErr<E = unknown>(value: unknown): value is Err<E>
+```
+
+- Returns `true` if `value` is a non-null object with the marker property set to `true`.
+- **Never throws** — handles `null`, `undefined`, primitives, and exceptions internally.
+
+```typescript
+const result: Result<number, string> = doSomething();
+
+if (isErr(result)) {
+  // result: Err<string>
+  console.error(result.data);
+} else {
+  // result: number
+  console.log(result + 1);
+}
+```
+
+> **Generic `E` caveat** — `isErr<E>()` provides a type assertion only. It does not validate the shape of `data` at runtime. Callers must ensure the generic matches the actual error type.
+
+<br>
+
+### `Result<T, E>`
+
+A plain union type — not a wrapper class.
+
+```typescript
+type Result<T, E = never> = T | Err<E>;
+```
+
+| Parameter | Default | Description |
+|:----------|:--------|:------------|
+| `T` | — | Success value type |
+| `E` | `never` | Error data type |
+
+```typescript
+// Simple — no error data
+type MayFail = Result<Config>;
+
+// With error data
+type ParseResult = Result<Config, string>;
+
+// Rich error types
+type ApiResult = Result<User, { code: string; message: string }>;
+```
+
+<br>
+
+### `Err<E>`
+
+The error type returned by `err()`.
+
+```typescript
+type Err<E = never> = {
+  stack: string;
+  data: E;
+};
+```
+
+> The marker property used for identification is deliberately excluded from the type. It is added internally by `err()` and checked by `isErr()` — this keeps the public API surface clean and prevents consumers from depending on implementation details.
+
+<br>
+
+### Marker Key
+
+The marker key is a unique hidden property used to identify `Err` objects. It defaults to a collision-resistant string.
+
+```typescript
+import { DEFAULT_MARKER_KEY, getMarkerKey, setMarkerKey } from '@zipbul/result';
+```
+
+| Export | Type | Description |
+|:-------|:-----|:------------|
+| `DEFAULT_MARKER_KEY` | `string` | `'__$$e_9f4a1c7b__'` — the default key |
+| `getMarkerKey()` | `() => string` | Returns the current marker key |
+| `setMarkerKey(key)` | `(key: string) => void` | Changes the marker key |
+
+```typescript
+// Reset detection across independent modules
+import { setMarkerKey, getMarkerKey } from '@zipbul/result';
+
+setMarkerKey('__my_app_err__');
+console.log(getMarkerKey()); // '__my_app_err__'
+```
+
+> **Validation** — `setMarkerKey()` throws `TypeError` if the key is empty or whitespace-only.
+>
+> **Warning** — changing the marker key means `isErr()` will no longer recognize `Err` objects created with the previous key. Only change this if you need to isolate error domains across independent modules.
+
+<br>
+
+## 🔬 Advanced Usage
+
+### Result-returning functions
+
+Define function signatures with `Result` to make error paths explicit in the type system.
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface ValidationError {
+  field: string;
+  message: string;
+}
+
+function validate(input: unknown): Result<ValidData, ValidationError> {
+  if (!input || typeof input !== 'object') {
+    return err({ field: 'root', message: 'Expected an object' });
+  }
+  // ... validation logic
+  return input as ValidData;
+}
+
+const result = validate(body);
+if (isErr(result)) {
+  return Response.json({ error: result.data }, { status: 400 });
+}
+// result is ValidData here
+```
+
+### Chaining results
+
+Since `Result` is a plain union, there's no `.map()` or `.flatMap()`. Use standard control flow:
+
+```typescript
+function processOrder(orderId: string): Result<Receipt, string> {
+  const order = findOrder(orderId);
+  if (isErr(order)) return order; // propagate
+
+  const payment = chargePayment(order);
+  if (isErr(payment)) return payment; // propagate
+
+  return generateReceipt(order, payment);
+}
+```
+
+> This is intentional. Classes with `.map()` / `.flatMap()` add runtime cost and force a specific composition style. Plain values + `isErr()` let you use standard `if`, `switch`, early return, and any other pattern you prefer.
+
+### Async results
+
+Works naturally with `Promise`:
+
+```typescript
+async function fetchUser(id: number): Promise<Result<User, ApiError>> {
+  try {
+    const res = await fetch(`/api/users/${id}`);
+    if (!res.ok) return err({ code: res.status, message: res.statusText });
+    return await res.json();
+  } catch {
+    return err({ code: 0, message: 'Network error' });
+  }
+}
+```
+
+### Stack traces
+
+Every `Err` captures a stack trace at creation time, enabling debugging without `throw`:
+
+```typescript
+const e = err('something went wrong');
+console.log(e.stack);
+// Error
+//     at err (/.../err.ts:22:18)
+//     at validate (/.../validate.ts:15:12)
+//     at handleRequest (/.../server.ts:8:20)
+```
+
+<br>
+
+## 🔌 Framework Integration Examples
+
+<details>
+<summary><b>Bun.serve</b></summary>
+
+```typescript
+import { err, isErr, type Result } from '@zipbul/result';
+
+interface AppError {
+  code: string;
+  message: string;
+}
+
+function parseBody(request: Request): Promise<Result<Payload, AppError>> {
+  // ... returns Result
+}
+
+Bun.serve({
+  async fetch(request) {
+    const body = await parseBody(request);
+
+    if (isErr(body)) {
+      return Response.json(
+        { error: body.data.code, message: body.data.message },
+        { status: 400 },
+      );
+    }
+
+    // body is Payload
+    return Response.json({ ok: true, data: process(body) });
+  },
+  port: 3000,
+});
+```
+
+</details>
+
+<details>
+<summary><b>With @zipbul/cors</b></summary>
+
+```typescript
+import { Cors, CorsAction } from '@zipbul/cors';
+import { isErr } from '@zipbul/result';
+
+const corsResult = Cors.create({
+  origin: 'https://app.example.com',
+  credentials: true,
+});
+
+// Cors.create() returns Result<Cors, CorsError>
+if (isErr(corsResult)) {
+  throw new Error(`CORS config error: ${corsResult.data.message}`);
+}
+
+const cors = corsResult;
+
+// cors.handle() returns Promise<Result<CorsResult, CorsError>>
+const result = await cors.handle(request);
+
+if (isErr(result)) {
+  return new Response('Internal Error', { status: 500 });
+}
+```
+
+</details>
+
+<br>
+
+## 📄 License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { err } from './src/err';
+export { isErr } from './src/is-err';
+export { DEFAULT_MARKER_KEY, getMarkerKey, setMarkerKey } from './src/constants';
+export type { Err, Result } from './src/types';

package/dist/index.js

@@ -0,0 +1,47 @@
+// @bun
+// src/constants.ts
+var DEFAULT_MARKER_KEY = "__$$e_9f4a1c7b__";
+var currentMarkerKey = DEFAULT_MARKER_KEY;
+function getMarkerKey() {
+  return currentMarkerKey;
+}
+function setMarkerKey(key) {
+  if (key.trim().length === 0) {
+    throw new TypeError("Marker key must be a non-empty string");
+  }
+  currentMarkerKey = key;
+}
+
+// src/err.ts
+function err(data) {
+  let stack;
+  try {
+    stack = new Error().stack ?? "";
+  } catch {
+    stack = "";
+  }
+  const result = {
+    [getMarkerKey()]: true,
+    stack,
+    data
+  };
+  return Object.freeze(result);
+}
+// src/is-err.ts
+function isErr(value) {
+  try {
+    return value !== null && value !== undefined && typeof value === "object" && value[getMarkerKey()] === true;
+  } catch {
+    return false;
+  }
+}
+export {
+  setMarkerKey,
+  isErr,
+  getMarkerKey,
+  err,
+  DEFAULT_MARKER_KEY
+};
+
+//# debugId=5E29B525CDB4D96664756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/constants.ts", "../src/err.ts", "../src/is-err.ts"],
+  "sourcesContent": [
+    "/**\n * 기본 에러 마커 키.\n * 에러 객체의 판별 프로퍼티명으로 사용된다.\n * zipbul 프레임워크와 무관한 유니크한 값으로, 충돌 가능성을 최소화한다.\n */\nexport const DEFAULT_MARKER_KEY = '__$$e_9f4a1c7b__';\n\nlet currentMarkerKey: string = DEFAULT_MARKER_KEY;\n\n/**\n * 현재 설정된 마커 키를 반환한다.\n *\n * @returns 현재 마커 키 문자열\n */\nexport function getMarkerKey(): string {\n  return currentMarkerKey;\n}\n\n/**\n * 마커 키를 변경한다.\n * error()와 isError()가 이 키를 참조하여 에러를 판별한다.\n * 빈 문자열 및 공백만으로 이루어진 문자열은 허용하지 않는다.\n *\n * @param key - 새 마커 키. 비어있지 않은(공백 제외) 문자열이어야 한다.\n * @throws {TypeError} key가 빈/공백 문자열인 경우\n */\nexport function setMarkerKey(key: string): void {\n  if (key.trim().length === 0) {\n    throw new TypeError('Marker key must be a non-empty string');\n  }\n  currentMarkerKey = key;\n}\n",
+    "import type { Err } from './types';\nimport { getMarkerKey } from './constants';\n\n/**\n * Err를 생성한다.\n * 절대 throw하지 않는다.\n * 반환 전 Object.freeze를 적용한다.\n *\n * @returns 동결(frozen)된 Err (data 없음)\n */\nexport function err(): Err;\n/**\n * @param data - 에러에 첨부할 데이터. 타입 무관.\n * @returns 동결(frozen)된 Err<E>\n */\nexport function err<E>(data: E): Err<E>;\nexport function err<E = never>(data?: E): Err<E> {\n  let stack: string;\n  try {\n    stack = new Error().stack ?? '';\n  } catch {\n    stack = '';\n  }\n\n  const result = {\n    [getMarkerKey()]: true,\n    stack,\n    data: data as E,\n  };\n\n  return Object.freeze(result) as Err<E>;\n}\n",
+    "import type { Err } from './types';\nimport { getMarkerKey } from './constants';\n\n/**\n * 값이 Err인지 판별하는 타입 가드.\n * 현재 설정된 마커 키(`getMarkerKey()`)에 해당하는 프로퍼티가\n * `=== true`인 경우에만 true를 반환한다.\n * 절대 throw하지 않는다.\n *\n * 주의: 제네릭 E는 런타임 검증 없이 타입 단언만 제공한다.\n * data의 구조는 호출자가 보장해야 한다.\n *\n * @param value - 판별 대상. 타입 무관.\n * @returns value가 Err이면 true\n */\nexport function isErr<E = unknown>(\n  value: unknown,\n): value is Err<E> {\n  try {\n    return (\n      value !== null &&\n      value !== undefined &&\n      typeof value === 'object' &&\n      (value as Record<string, unknown>)[getMarkerKey()] === true\n    );\n  } catch {\n    return false;\n  }\n}\n"
+  ],
+  "mappings": ";;AAKO,IAAM,qBAAqB;AAElC,IAAI,mBAA2B;AAOxB,SAAS,YAAY,GAAW;AAAA,EACrC,OAAO;AAAA;AAWF,SAAS,YAAY,CAAC,KAAmB;AAAA,EAC9C,IAAI,IAAI,KAAK,EAAE,WAAW,GAAG;AAAA,IAC3B,MAAM,IAAI,UAAU,uCAAuC;AAAA,EAC7D;AAAA,EACA,mBAAmB;AAAA;;;ACdd,SAAS,GAAc,CAAC,MAAkB;AAAA,EAC/C,IAAI;AAAA,EACJ,IAAI;AAAA,IACF,QAAQ,IAAI,MAAM,EAAE,SAAS;AAAA,IAC7B,MAAM;AAAA,IACN,QAAQ;AAAA;AAAA,EAGV,MAAM,SAAS;AAAA,KACZ,aAAa,IAAI;AAAA,IAClB;AAAA,IACA;AAAA,EACF;AAAA,EAEA,OAAO,OAAO,OAAO,MAAM;AAAA;;ACftB,SAAS,KAAkB,CAChC,OACiB;AAAA,EACjB,IAAI;AAAA,IACF,OACE,UAAU,QACV,UAAU,aACV,OAAO,UAAU,YAChB,MAAkC,aAAa,OAAO;AAAA,IAEzD,MAAM;AAAA,IACN,OAAO;AAAA;AAAA;",
+  "debugId": "5E29B525CDB4D96664756E2164756E21",
+  "names": []
+}

package/dist/src/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 기본 에러 마커 키.
+ * 에러 객체의 판별 프로퍼티명으로 사용된다.
+ * zipbul 프레임워크와 무관한 유니크한 값으로, 충돌 가능성을 최소화한다.
+ */
+export declare const DEFAULT_MARKER_KEY = "__$$e_9f4a1c7b__";
+/**
+ * 현재 설정된 마커 키를 반환한다.
+ *
+ * @returns 현재 마커 키 문자열
+ */
+export declare function getMarkerKey(): string;
+/**
+ * 마커 키를 변경한다.
+ * error()와 isError()가 이 키를 참조하여 에러를 판별한다.
+ * 빈 문자열 및 공백만으로 이루어진 문자열은 허용하지 않는다.
+ *
+ * @param key - 새 마커 키. 비어있지 않은(공백 제외) 문자열이어야 한다.
+ * @throws {TypeError} key가 빈/공백 문자열인 경우
+ */
+export declare function setMarkerKey(key: string): void;

package/dist/src/err.d.ts

@@ -0,0 +1,14 @@
+import type { Err } from './types';
+/**
+ * Err를 생성한다.
+ * 절대 throw하지 않는다.
+ * 반환 전 Object.freeze를 적용한다.
+ *
+ * @returns 동결(frozen)된 Err (data 없음)
+ */
+export declare function err(): Err;
+/**
+ * @param data - 에러에 첨부할 데이터. 타입 무관.
+ * @returns 동결(frozen)된 Err<E>
+ */
+export declare function err<E>(data: E): Err<E>;

package/dist/src/is-err.d.ts

@@ -0,0 +1,14 @@
+import type { Err } from './types';
+/**
+ * 값이 Err인지 판별하는 타입 가드.
+ * 현재 설정된 마커 키(`getMarkerKey()`)에 해당하는 프로퍼티가
+ * `=== true`인 경우에만 true를 반환한다.
+ * 절대 throw하지 않는다.
+ *
+ * 주의: 제네릭 E는 런타임 검증 없이 타입 단언만 제공한다.
+ * data의 구조는 호출자가 보장해야 한다.
+ *
+ * @param value - 판별 대상. 타입 무관.
+ * @returns value가 Err이면 true
+ */
+export declare function isErr<E = unknown>(value: unknown): value is Err<E>;

package/dist/src/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 에러 타입.
+ * 마커 프로퍼티는 타입에 포함하지 않는다.
+ * err() 함수가 런타임에 마커를 동적 추가하며,
+ * isErr() 타입 가드를 통해서만 판별한다.
+ *
+ * @template E - 에러에 첨부할 추가 데이터의 타입. 기본값은 never.
+ */
+export type Err<E = never> = {
+    stack: string;
+    data: E;
+};
+/**
+ * 성공(T) 또는 에러(Err<E>)를 표현하는 유니온 타입.
+ * wrapper 클래스가 아닌 plain union으로, 런타임 오버헤드가 없다.
+ *
+ * @template T - 성공값 타입
+ * @template E - 에러 데이터 타입. 기본값은 never.
+ */
+export type Result<T, E = never> = T | Err<E>;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@zipbul/result",
+  "version": "0.0.1",
+  "description": "Lightweight Result type for error handling without exceptions",
+  "license": "MIT",
+  "author": "Junhyung Park (https://github.com/parkrevil)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zipbul/toolkit",
+    "directory": "packages/result"
+  },
+  "bugs": "https://github.com/zipbul/toolkit/issues",
+  "homepage": "https://github.com/zipbul/toolkit/tree/main/packages/result#readme",
+  "keywords": ["result", "error", "either", "typescript", "zipbul"],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "bun build index.ts --outdir dist --target bun --format esm --sourcemap=linked && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "coverage": "bun test --coverage"
+  }
+}