@zipbul/result 0.0.3 → 0.1.0

package/README.ko.md

@@ -207,6 +207,82 @@ type Err<E = never> = {
 
 <br>
 
+### `safe()`
+
+동기 함수 또는 Promise를 `Result` / `ResultAsync`로 감쌉니다. throw와 rejection을 캐치하여 `Err`로 변환합니다.
+
+```typescript
+import { safe } from '@zipbul/result';
+```
+
+| 오버로드 | 반환 | 설명 |
+|:---------|:-----|:-----|
+| `safe(fn)` | `Result<T, unknown>` | 동기 — `fn()` 호출, throw 캐치 |
+| `safe(fn, mapErr)` | `Result<T, E>` | 동기 — throw 캐치, `mapErr`로 변환 |
+| `safe(promise)` | `ResultAsync<T, unknown>` | 비동기 — rejection 래핑 |
+| `safe(promise, mapErr)` | `ResultAsync<T, E>` | 비동기 — rejection 래핑, `mapErr`로 변환 |
+
+```typescript
+// 동기 — throw할 수 있는 함수 래핑
+const result = safe(() => JSON.parse(rawJson));
+if (isErr(result)) {
+  console.error('파싱 실패:', result.data);
+} else {
+  console.log(result); // 파싱된 객체
+}
+
+// 동기 + mapErr — unknown throw를 타입이 있는 에러로 변환
+const typed = safe(
+  () => JSON.parse(rawJson),
+  (e) => ({ code: 'PARSE_ERROR', message: String(e) }),
+);
+
+// 비동기 — reject될 수 있는 Promise 래핑
+const asyncResult = await safe(fetch('/api/data'));
+
+// 비동기 + mapErr
+const apiResult = await safe(
+  fetch('/api/users/1'),
+  (e) => ({ code: 'NETWORK', message: String(e) }),
+);
+```
+
+> **동기 경로** — `safe(fn)`은 `!(fn instanceof Promise)`로 함수를 감지합니다. Promise를 _반환하는_ 함수는 동기로 처리되며, Promise 객체가 성공값 `T`가 됩니다.
+>
+> **mapErr 패닉** — `mapErr` 자체가 throw하면, 동기의 경우 throw가 전파되고 비동기의 경우 반환된 promise가 reject됩니다. 이는 의도된 설계입니다 — `mapErr`는 사용자 코드이며, 그 실패는 패닉(panic)이지 `Err`가 아닙니다.
+
+<br>
+
+### `ResultAsync<T, E>`
+
+비동기 결과를 위한 타입 별칭 — 래퍼 클래스가 아닙니다.
+
+```typescript
+type ResultAsync<T, E = never> = Promise<Result<T, E>>;
+```
+
+| 파라미터 | 기본값 | 설명 |
+|:---------|:-------|:-----|
+| `T` | — | 성공 값 타입 |
+| `E` | `never` | 에러 데이터 타입 |
+
+```typescript
+// 비동기 Result 반환 함수의 반환 타입으로 사용
+async function fetchUser(id: number): ResultAsync<User, string> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) return err(res.statusText);
+  return await res.json();
+}
+
+// 또는 기존 Promise를 safe()로 래핑
+const result: ResultAsync<Response, string> = safe(
+  fetch('/api/data'),
+  (e) => String(e),
+);
+```
+
+<br>
+
 ### 마커 키(Marker Key)
 
 마커 키는 `Err` 객체를 식별하는 데 사용되는 숨겨진 고유 프로퍼티입니다. 충돌에 강한 문자열이 기본값입니다.

package/README.md

@@ -207,6 +207,82 @@ type Err<E = never> = {
 
 <br>
 
+### `safe()`
+
+Wraps a sync function or Promise into a `Result` / `ResultAsync`. Catches throws and rejections, converting them to `Err`.
+
+```typescript
+import { safe } from '@zipbul/result';
+```
+
+| Overload | Return | Description |
+|:---------|:-------|:------------|
+| `safe(fn)` | `Result<T, unknown>` | Sync — calls `fn()`, catches throws |
+| `safe(fn, mapErr)` | `Result<T, E>` | Sync — catches throws, maps via `mapErr` |
+| `safe(promise)` | `ResultAsync<T, unknown>` | Async — wraps rejection |
+| `safe(promise, mapErr)` | `ResultAsync<T, E>` | Async — wraps rejection, maps via `mapErr` |
+
+```typescript
+// Sync — wrap a function that might throw
+const result = safe(() => JSON.parse(rawJson));
+if (isErr(result)) {
+  console.error('Parse failed:', result.data);
+} else {
+  console.log(result); // parsed object
+}
+
+// Sync with mapErr — convert unknown throw to typed error
+const typed = safe(
+  () => JSON.parse(rawJson),
+  (e) => ({ code: 'PARSE_ERROR', message: String(e) }),
+);
+
+// Async — wrap a Promise that might reject
+const asyncResult = await safe(fetch('/api/data'));
+
+// Async with mapErr
+const apiResult = await safe(
+  fetch('/api/users/1'),
+  (e) => ({ code: 'NETWORK', message: String(e) }),
+);
+```
+
+> **Sync path** — `safe(fn)` detects a function via `!(fn instanceof Promise)`. A function that _returns_ a Promise is treated as sync — the Promise object becomes the success value `T`.
+>
+> **mapErr panic** — if `mapErr` itself throws, the throw propagates (sync) or the returned promise rejects (async). This is by design — `mapErr` is user code, and its failure is a panic, not an `Err`.
+
+<br>
+
+### `ResultAsync<T, E>`
+
+A type alias for async results — not a wrapper class.
+
+```typescript
+type ResultAsync<T, E = never> = Promise<Result<T, E>>;
+```
+
+| Parameter | Default | Description |
+|:----------|:--------|:------------|
+| `T` | — | Success value type |
+| `E` | `never` | Error data type |
+
+```typescript
+// Use as return type for async Result-returning functions
+async function fetchUser(id: number): ResultAsync<User, string> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) return err(res.statusText);
+  return await res.json();
+}
+
+// Or wrap an existing Promise with safe()
+const result: ResultAsync<Response, string> = safe(
+  fetch('/api/data'),
+  (e) => String(e),
+);
+```
+
+<br>
+
 ### Marker Key
 
 The marker key is a unique hidden property used to identify `Err` objects. It defaults to a collision-resistant string.

package/dist/index.d.ts

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

package/dist/index.js

@@ -35,13 +35,25 @@ function isErr(value) {
     return false;
   }
 }
+// src/safe.ts
+function safe(fnOrPromise, mapErr) {
+  if (fnOrPromise instanceof Promise) {
+    return fnOrPromise.then((value) => value, (thrown) => mapErr ? err(mapErr(thrown)) : err(thrown));
+  }
+  try {
+    return fnOrPromise();
+  } catch (thrown) {
+    return mapErr ? err(mapErr(thrown)) : err(thrown);
+  }
+}
 export {
   setMarkerKey,
+  safe,
   isErr,
   getMarkerKey,
   err,
   DEFAULT_MARKER_KEY
 };
 
-//# debugId=5E29B525CDB4D96664756E2164756E21
+//# debugId=6EA5CE9688A72DB264756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,12 +1,13 @@
 {
   "version": 3,
-  "sources": ["../src/constants.ts", "../src/err.ts", "../src/is-err.ts"],
+  "sources": ["../src/constants.ts", "../src/err.ts", "../src/is-err.ts", "../src/safe.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"
+    "/**\n * The default marker key used to identify {@link Err} objects.\n *\n * This collision-resistant string is set as a hidden property on every `Err`\n * created by `err()`. You rarely need to reference it directly — it is\n * provided for advanced use cases like cross-module error domain isolation.\n *\n * @example\n * ```ts\n * import { DEFAULT_MARKER_KEY } from '@zipbul/result';\n * console.log(DEFAULT_MARKER_KEY); // '__$$e_9f4a1c7b__'\n * ```\n */\nexport const DEFAULT_MARKER_KEY = '__$$e_9f4a1c7b__';\n\nlet currentMarkerKey: string = DEFAULT_MARKER_KEY;\n\n/**\n * Returns the marker key currently in use.\n *\n * Both `err()` and `isErr()` rely on this key to tag and detect error objects.\n *\n * @returns The current marker key string.\n *\n * @example\n * ```ts\n * console.log(getMarkerKey()); // '__$$e_9f4a1c7b__'\n * ```\n */\nexport function getMarkerKey(): string {\n  return currentMarkerKey;\n}\n\n/**\n * Replaces the marker key used by `err()` and `isErr()`.\n *\n * After calling this, newly-created `Err` objects will use the new key, and\n * `isErr()` will only recognise objects carrying the new key. Previously\n * created `Err` objects will **no longer** be detected.\n *\n * Only change this if you need to isolate error domains across independent\n * modules — in most applications the default key is perfectly fine.\n *\n * @param key - A non-empty, non-whitespace-only string to use as the new key.\n * @throws {TypeError} If `key` is empty or contains only whitespace.\n *\n * @example\n * ```ts\n * setMarkerKey('__my_app_err__');\n * console.log(getMarkerKey()); // '__my_app_err__'\n * ```\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 * Creates an immutable {@link Err} value with no attached data.\n *\n * The returned object is `Object.freeze()`-d and includes a stack trace\n * captured at the call site. This function **never throws**.\n *\n * @returns A frozen `Err` with `data` typed as `never`.\n *\n * @example\n * ```ts\n * const e = err();\n * console.log(e.stack); // stack trace\n * ```\n */\nexport function err(): Err;\n/**\n * Creates an immutable {@link Err} value carrying the given data.\n *\n * The returned object is `Object.freeze()`-d and includes a stack trace\n * captured at the call site. This function **never throws**.\n *\n * @param data - Any value describing the error (string, object, number, etc.).\n * @returns A frozen `Err<E>` with `data` set to the provided value.\n *\n * @example\n * ```ts\n * const e = err({ code: 'TIMEOUT', retryAfter: 3000 });\n * console.log(e.data.code); // 'TIMEOUT'\n * ```\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 * Type guard that checks whether a value is an {@link Err}.\n *\n * Returns `true` when `value` is a non-null object whose current marker\n * property is strictly `true`. This function **never throws** — it safely\n * handles `null`, `undefined`, primitives, and even hostile Proxy objects.\n *\n * **Note:** The generic `E` is a compile-time assertion only. It does **not**\n * validate the shape of `data` at runtime — callers must ensure `E` matches\n * the actual error type.\n *\n * @typeParam E - Expected error data type (default: `unknown`).\n * @param value - The value to check. Can be anything.\n * @returns `true` if `value` is an `Err`, allowing TypeScript to narrow the type.\n *\n * @example\n * ```ts\n * const result: Result<number, string> = doSomething();\n *\n * if (isErr(result)) {\n *   console.error(result.data); // string\n * } else {\n *   console.log(result + 1);    // number\n * }\n * ```\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",
+    "import type { Result, ResultAsync } from './types';\nimport { err } from './err';\n\n/**\n * Executes a synchronous function and catches any thrown value into an {@link Err}.\n *\n * If `fn` returns normally, its return value is passed through as the success\n * value. If `fn` throws, the thrown value is wrapped with `err()` and returned.\n *\n * @param fn - A synchronous function to execute safely.\n * @returns The function's return value on success, or `Err<unknown>` on throw.\n *\n * @example\n * ```ts\n * const result = safe(() => JSON.parse(raw));\n * if (isErr(result)) console.error(result.data);\n * ```\n */\nexport function safe<T>(fn: () => T): Result<T, unknown>;\n/**\n * Executes a synchronous function and maps any thrown value through `mapErr`\n * before wrapping it in an {@link Err}.\n *\n * This overload lets you convert the raw `unknown` throw into a well-typed\n * error value, keeping your error types precise.\n *\n * @param fn - A synchronous function to execute safely.\n * @param mapErr - Transforms the thrown value into a typed error `E`.\n * @returns The function's return value on success, or `Err<E>` on throw.\n *\n * @example\n * ```ts\n * const result = safe(\n *   () => JSON.parse(raw),\n *   (e) => ({ code: 'PARSE', message: String(e) }),\n * );\n * ```\n */\nexport function safe<T, E>(fn: () => T, mapErr: (thrown: unknown) => E): Result<T, E>;\n/**\n * Wraps a Promise so that rejections become {@link Err} values instead of\n * thrown exceptions.\n *\n * If the promise resolves, the resolved value is passed through. If it\n * rejects, the rejection reason is wrapped with `err()` and the returned\n * promise resolves (never rejects) to `Err<unknown>`.\n *\n * @param promise - The promise to wrap.\n * @returns A `ResultAsync` that always resolves — either to `T` or to `Err<unknown>`.\n *\n * @example\n * ```ts\n * const result = await safe(fetch('/api/data'));\n * ```\n */\nexport function safe<T>(promise: Promise<T>): ResultAsync<T, unknown>;\n/**\n * Wraps a Promise so that rejections are mapped through `mapErr` and returned\n * as typed {@link Err} values.\n *\n * Combines the safety of promise wrapping with precise error typing.\n *\n * @param promise - The promise to wrap.\n * @param mapErr - Transforms the rejection reason into a typed error `E`.\n * @returns A `ResultAsync` that always resolves — either to `T` or to `Err<E>`.\n *\n * @example\n * ```ts\n * const result = await safe(\n *   fetch('/api/users/1'),\n *   (e) => ({ code: 'NETWORK', message: String(e) }),\n * );\n * ```\n */\nexport function safe<T, E>(promise: Promise<T>, mapErr: (thrown: unknown) => E): ResultAsync<T, E>;\nexport function safe<T, E = unknown>(\n  fnOrPromise: (() => T) | Promise<T>,\n  mapErr?: (thrown: unknown) => E,\n): Result<T, E> | ResultAsync<T, E> {\n  if (fnOrPromise instanceof Promise) {\n    return fnOrPromise.then(\n      (value) => value as Result<T, E>,\n      (thrown: unknown) => (mapErr ? err(mapErr(thrown)) : err(thrown)) as Result<T, E>,\n    );\n  }\n\n  try {\n    return fnOrPromise();\n  } catch (thrown: unknown) {\n    return mapErr ? err(mapErr(thrown)) : err(thrown as E);\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",
+  "mappings": ";;AAaO,IAAM,qBAAqB;AAElC,IAAI,mBAA2B;AAcxB,SAAS,YAAY,GAAW;AAAA,EACrC,OAAO;AAAA;AAsBF,SAAS,YAAY,CAAC,KAAmB;AAAA,EAC9C,IAAI,IAAI,KAAK,EAAE,WAAW,GAAG;AAAA,IAC3B,MAAM,IAAI,UAAU,uCAAuC;AAAA,EAC7D;AAAA,EACA,mBAAmB;AAAA;;;ACtBd,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;;ACnBtB,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;;ACmCJ,SAAS,IAAoB,CAClC,aACA,QACkC;AAAA,EAClC,IAAI,uBAAuB,SAAS;AAAA,IAClC,OAAO,YAAY,KACjB,CAAC,UAAU,OACX,CAAC,WAAqB,SAAS,IAAI,OAAO,MAAM,CAAC,IAAI,IAAI,MAAM,CACjE;AAAA,EACF;AAAA,EAEA,IAAI;AAAA,IACF,OAAO,YAAY;AAAA,IACnB,OAAO,QAAiB;AAAA,IACxB,OAAO,SAAS,IAAI,OAAO,MAAM,CAAC,IAAI,IAAI,MAAW;AAAA;AAAA;",
+  "debugId": "6EA5CE9688A72DB264756E2164756E21",
   "names": []
 }

package/dist/src/constants.d.ts

@@ -1,21 +1,47 @@
 /**
- * 기본 에러 마커 키.
- * 에러 객체의 판별 프로퍼티명으로 사용된다.
- * zipbul 프레임워크와 무관한 유니크한 값으로, 충돌 가능성을 최소화한다.
+ * The default marker key used to identify {@link Err} objects.
+ *
+ * This collision-resistant string is set as a hidden property on every `Err`
+ * created by `err()`. You rarely need to reference it directly — it is
+ * provided for advanced use cases like cross-module error domain isolation.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MARKER_KEY } from '@zipbul/result';
+ * console.log(DEFAULT_MARKER_KEY); // '__$$e_9f4a1c7b__'
+ * ```
  */
 export declare const DEFAULT_MARKER_KEY = "__$$e_9f4a1c7b__";
 /**
- * 현재 설정된 마커 키를 반환한다.
+ * Returns the marker key currently in use.
+ *
+ * Both `err()` and `isErr()` rely on this key to tag and detect error objects.
+ *
+ * @returns The current marker key string.
  *
- * @returns 현재 마커 키 문자열
+ * @example
+ * ```ts
+ * console.log(getMarkerKey()); // '__$$e_9f4a1c7b__'
+ * ```
  */
 export declare function getMarkerKey(): string;
 /**
- * 마커 키를 변경한다.
- * error()와 isError()가 이 키를 참조하여 에러를 판별한다.
- * 빈 문자열 및 공백만으로 이루어진 문자열은 허용하지 않는다.
+ * Replaces the marker key used by `err()` and `isErr()`.
+ *
+ * After calling this, newly-created `Err` objects will use the new key, and
+ * `isErr()` will only recognise objects carrying the new key. Previously
+ * created `Err` objects will **no longer** be detected.
+ *
+ * Only change this if you need to isolate error domains across independent
+ * modules — in most applications the default key is perfectly fine.
+ *
+ * @param key - A non-empty, non-whitespace-only string to use as the new key.
+ * @throws {TypeError} If `key` is empty or contains only whitespace.
  *
- * @param key - 새 마커 키. 비어있지 않은(공백 제외) 문자열이어야 한다.
- * @throws {TypeError} key가 빈/공백 문자열인 경우
+ * @example
+ * ```ts
+ * setMarkerKey('__my_app_err__');
+ * console.log(getMarkerKey()); // '__my_app_err__'
+ * ```
  */
 export declare function setMarkerKey(key: string): void;

package/dist/src/err.d.ts

@@ -1,14 +1,32 @@
 import type { Err } from './types';
 /**
- * Err를 생성한다.
- * 절대 throw하지 않는다.
- * 반환 전 Object.freeze를 적용한다.
+ * Creates an immutable {@link Err} value with no attached data.
  *
- * @returns 동결(frozen)된 Err (data 없음)
+ * The returned object is `Object.freeze()`-d and includes a stack trace
+ * captured at the call site. This function **never throws**.
+ *
+ * @returns A frozen `Err` with `data` typed as `never`.
+ *
+ * @example
+ * ```ts
+ * const e = err();
+ * console.log(e.stack); // stack trace
+ * ```
  */
 export declare function err(): Err;
 /**
- * @param data - 에러에 첨부할 데이터. 타입 무관.
- * @returns 동결(frozen)된 Err<E>
+ * Creates an immutable {@link Err} value carrying the given data.
+ *
+ * The returned object is `Object.freeze()`-d and includes a stack trace
+ * captured at the call site. This function **never throws**.
+ *
+ * @param data - Any value describing the error (string, object, number, etc.).
+ * @returns A frozen `Err<E>` with `data` set to the provided value.
+ *
+ * @example
+ * ```ts
+ * const e = err({ code: 'TIMEOUT', retryAfter: 3000 });
+ * console.log(e.data.code); // 'TIMEOUT'
+ * ```
  */
 export declare function err<E>(data: E): Err<E>;

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

@@ -1,14 +1,28 @@
 import type { Err } from './types';
 /**
- * 값이 Err인지 판별하는 타입 가드.
- * 현재 설정된 마커 키(`getMarkerKey()`)에 해당하는 프로퍼티가
- * `=== true`인 경우에만 true를 반환한다.
- * 절대 throw하지 않는다.
+ * Type guard that checks whether a value is an {@link Err}.
  *
- * 주의: 제네릭 E는 런타임 검증 없이 타입 단언만 제공한다.
- * data의 구조는 호출자가 보장해야 한다.
+ * Returns `true` when `value` is a non-null object whose current marker
+ * property is strictly `true`. This function **never throws** — it safely
+ * handles `null`, `undefined`, primitives, and even hostile Proxy objects.
  *
- * @param value - 판별 대상. 타입 무관.
- * @returns value가 Err이면 true
+ * **Note:** The generic `E` is a compile-time assertion only. It does **not**
+ * validate the shape of `data` at runtime — callers must ensure `E` matches
+ * the actual error type.
+ *
+ * @typeParam E - Expected error data type (default: `unknown`).
+ * @param value - The value to check. Can be anything.
+ * @returns `true` if `value` is an `Err`, allowing TypeScript to narrow the type.
+ *
+ * @example
+ * ```ts
+ * const result: Result<number, string> = doSomething();
+ *
+ * if (isErr(result)) {
+ *   console.error(result.data); // string
+ * } else {
+ *   console.log(result + 1);    // number
+ * }
+ * ```
  */
 export declare function isErr<E = unknown>(value: unknown): value is Err<E>;

package/dist/src/safe.d.ts

@@ -0,0 +1,73 @@
+import type { Result, ResultAsync } from './types';
+/**
+ * Executes a synchronous function and catches any thrown value into an {@link Err}.
+ *
+ * If `fn` returns normally, its return value is passed through as the success
+ * value. If `fn` throws, the thrown value is wrapped with `err()` and returned.
+ *
+ * @param fn - A synchronous function to execute safely.
+ * @returns The function's return value on success, or `Err<unknown>` on throw.
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw));
+ * if (isErr(result)) console.error(result.data);
+ * ```
+ */
+export declare function safe<T>(fn: () => T): Result<T, unknown>;
+/**
+ * Executes a synchronous function and maps any thrown value through `mapErr`
+ * before wrapping it in an {@link Err}.
+ *
+ * This overload lets you convert the raw `unknown` throw into a well-typed
+ * error value, keeping your error types precise.
+ *
+ * @param fn - A synchronous function to execute safely.
+ * @param mapErr - Transforms the thrown value into a typed error `E`.
+ * @returns The function's return value on success, or `Err<E>` on throw.
+ *
+ * @example
+ * ```ts
+ * const result = safe(
+ *   () => JSON.parse(raw),
+ *   (e) => ({ code: 'PARSE', message: String(e) }),
+ * );
+ * ```
+ */
+export declare function safe<T, E>(fn: () => T, mapErr: (thrown: unknown) => E): Result<T, E>;
+/**
+ * Wraps a Promise so that rejections become {@link Err} values instead of
+ * thrown exceptions.
+ *
+ * If the promise resolves, the resolved value is passed through. If it
+ * rejects, the rejection reason is wrapped with `err()` and the returned
+ * promise resolves (never rejects) to `Err<unknown>`.
+ *
+ * @param promise - The promise to wrap.
+ * @returns A `ResultAsync` that always resolves — either to `T` or to `Err<unknown>`.
+ *
+ * @example
+ * ```ts
+ * const result = await safe(fetch('/api/data'));
+ * ```
+ */
+export declare function safe<T>(promise: Promise<T>): ResultAsync<T, unknown>;
+/**
+ * Wraps a Promise so that rejections are mapped through `mapErr` and returned
+ * as typed {@link Err} values.
+ *
+ * Combines the safety of promise wrapping with precise error typing.
+ *
+ * @param promise - The promise to wrap.
+ * @param mapErr - Transforms the rejection reason into a typed error `E`.
+ * @returns A `ResultAsync` that always resolves — either to `T` or to `Err<E>`.
+ *
+ * @example
+ * ```ts
+ * const result = await safe(
+ *   fetch('/api/users/1'),
+ *   (e) => ({ code: 'NETWORK', message: String(e) }),
+ * );
+ * ```
+ */
+export declare function safe<T, E>(promise: Promise<T>, mapErr: (thrown: unknown) => E): ResultAsync<T, E>;

package/dist/src/types.d.ts

@@ -1,20 +1,58 @@
 /**
- * 에러 타입.
- * 마커 프로퍼티는 타입에 포함하지 않는다.
- * err() 함수가 런타임에 마커를 동적 추가하며,
- * isErr() 타입 가드를 통해서만 판별한다.
+ * The error type returned by {@link err}.
  *
- * @template E - 에러에 첨부할 추가 데이터의 타입. 기본값은 never.
+ * Every `Err` carries a `stack` trace captured at creation and an optional
+ * `data` payload describing what went wrong. The hidden marker property used
+ * for detection is intentionally excluded from the type — it is managed
+ * internally by `err()` and checked only through `isErr()`.
+ *
+ * @template E - The type of the attached error data. Defaults to `never`.
+ *
+ * @example
+ * ```ts
+ * const e: Err<string> = err('not found');
+ * console.log(e.data);  // 'not found'
+ * console.log(e.stack); // stack trace string
+ * ```
  */
 export type Err<E = never> = {
     stack: string;
     data: E;
 };
 /**
- * 성공(T) 또는 에러(Err<E>)를 표현하는 유니온 타입.
- * wrapper 클래스가 아닌 plain union으로, 런타임 오버헤드가 없다.
+ * A plain union representing either a success value (`T`) or an error (`Err<E>`).
+ *
+ * Unlike wrapper-class approaches, `Result` is just `T | Err<E>` — zero
+ * runtime overhead, full type safety. Use {@link isErr} to narrow the type.
  *
- * @template T - 성공값 타입
- * @template E - 에러 데이터 타입. 기본값은 never.
+ * @template T - The success value type.
+ * @template E - The error data type. Defaults to `never`.
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return err('division by zero');
+ *   return a / b;
+ * }
+ * ```
  */
 export type Result<T, E = never> = T | Err<E>;
+/**
+ * A convenient type alias for asynchronous results.
+ *
+ * This is simply `Promise<Result<T, E>>` — no wrapper class, no extra
+ * abstraction. Use it as a return type for async functions that may fail.
+ *
+ * @template T - The success value type.
+ * @template E - The error data type. Defaults to `never`.
+ *
+ * @example
+ * ```ts
+ * async function fetchUser(id: number): ResultAsync<User, string> {
+ *   const res = await fetch(`/api/users/${id}`);
+ *   if (!res.ok) return err(res.statusText);
+ *   return await res.json();
+ * }
+ * ```
+ */
+export type ResultAsync<T, E = never> = Promise<Result<T, E>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zipbul/result",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Lightweight Result type for error handling without exceptions",
   "license": "MIT",
   "author": "Junhyung Park (https://github.com/parkrevil)",
@@ -35,6 +35,7 @@
   ],
   "scripts": {
     "build": "bun build index.ts --outdir dist --target bun --format esm --sourcemap=linked && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
     "test": "bun test",
     "coverage": "bun test --coverage"
   }