Antigravity Agent
230 lines
6.9 KiB
Markdown
230 lines
6.9 KiB
Markdown
---
|
|
id: wiki-2026-0508-effect-ts-및-ts-brand-라이브러리-활용
|
|
title: Effect TS 및 ts-brand 라이브러리 활용
|
|
category: 10_Wiki/Topics
|
|
status: verified
|
|
canonical_id: self
|
|
aliases: [Effect-TS, ts-brand, Branded Types, Effect.gen]
|
|
duplicate_of: none
|
|
source_trust_level: A
|
|
confidence_score: 0.9
|
|
verification_status: applied
|
|
tags: [typescript, functional, effect-system, branded-types]
|
|
raw_sources: []
|
|
last_reinforced: 2026-05-10
|
|
github_commit: pending
|
|
tech_stack:
|
|
language: TypeScript
|
|
framework: Effect
|
|
---
|
|
|
|
# Effect TS 및 ts-brand 라이브러리 활용
|
|
|
|
## 매 한 줄
|
|
> **"매 typed effect system + nominal type 의 — TypeScript 의 의 ZIO/Cats 의 imported"**. Effect 의 의 async/error/dependency 의 의 single 의 `Effect<A, E, R>` 의 의 unify, ts-brand 의 의 structural type 의 의 nominal flavor 의 의 add. 2026 의 매 enterprise TS codebase 의 의 fast 의 emerging.
|
|
|
|
## 매 핵심
|
|
|
|
### 매 Effect 의 type
|
|
- `Effect<A, E, R>` — 의 success `A`, 의 failure `E`, 의 requirement `R`.
|
|
- 매 lazy — 매 `Effect.runPromise` / `Effect.runSync` 의 의 actual 의 execute.
|
|
- 의 composable — `pipe`, `Effect.gen` 의 의 chain.
|
|
|
|
### 매 ts-brand 의 nominal type
|
|
- 의 TypeScript structural — `string === string` 의 의 distinguishable X.
|
|
- Brand 의 의 `string & { __brand: "UserId" }` 의 의 phantom tag.
|
|
- 의 runtime cost zero — type-level only.
|
|
|
|
### 매 응용
|
|
1. Domain ID (UserId, OrderId 의 의 mix-up 의 prevent).
|
|
2. Validated value (Email, NonEmptyString).
|
|
3. Async pipeline 의 typed error.
|
|
4. Dependency injection (Effect Layer).
|
|
5. Retry/timeout/concurrency 의 declarative.
|
|
|
|
## 💻 패턴
|
|
|
|
### ts-brand 기본
|
|
```ts
|
|
import type { Brand } from "ts-brand";
|
|
|
|
type UserId = Brand<string, "UserId">;
|
|
type OrderId = Brand<string, "OrderId">;
|
|
|
|
const makeUserId = (s: string): UserId => s as UserId;
|
|
|
|
function getUser(id: UserId) { /* ... */ }
|
|
|
|
const uid = makeUserId("u_123");
|
|
const oid = "o_456" as OrderId;
|
|
|
|
getUser(uid);
|
|
// getUser(oid); // 매 compile error — UserId 의 X
|
|
// getUser("u_123"); // 매 compile error — raw string
|
|
```
|
|
|
|
### Validated brand (smart constructor)
|
|
```ts
|
|
type Email = Brand<string, "Email">;
|
|
|
|
function parseEmail(s: string): Email | null {
|
|
return /^[^@]+@[^@]+\.[^@]+$/.test(s) ? (s as Email) : null;
|
|
}
|
|
|
|
function sendMail(to: Email, subject: string) { /* ... */ }
|
|
|
|
const e = parseEmail(input);
|
|
if (e) sendMail(e, "hi"); // 매 type-narrowed 의 valid 의 only
|
|
```
|
|
|
|
### Effect 기본
|
|
```ts
|
|
import { Effect, pipe } from "effect";
|
|
|
|
const fetchUser = (id: UserId): Effect.Effect<User, NetworkError | NotFoundError> =>
|
|
Effect.tryPromise({
|
|
try: () => fetch(`/api/users/${id}`).then((r) => {
|
|
if (r.status === 404) throw new NotFoundError(id);
|
|
return r.json();
|
|
}),
|
|
catch: (e) => e instanceof NotFoundError ? e : new NetworkError(e),
|
|
});
|
|
|
|
const program = pipe(
|
|
fetchUser(uid),
|
|
Effect.map((u) => u.email),
|
|
Effect.tap((email) => Effect.log(`Got: ${email}`)),
|
|
);
|
|
|
|
Effect.runPromise(program).then(console.log);
|
|
```
|
|
|
|
### Effect.gen (do-notation)
|
|
```ts
|
|
import { Effect } from "effect";
|
|
|
|
const program = Effect.gen(function* () {
|
|
const user = yield* fetchUser(uid);
|
|
const orders = yield* fetchOrders(user.id);
|
|
const valid = orders.filter((o) => o.status === "paid");
|
|
return { user, orderCount: valid.length };
|
|
});
|
|
```
|
|
|
|
### Typed retry / timeout
|
|
```ts
|
|
import { Effect, Schedule, Duration } from "effect";
|
|
|
|
const robust = pipe(
|
|
fetchUser(uid),
|
|
Effect.retry(Schedule.exponential(Duration.millis(100)).pipe(Schedule.compose(Schedule.recurs(3)))),
|
|
Effect.timeout(Duration.seconds(5)),
|
|
);
|
|
```
|
|
|
|
### Layer / dependency injection
|
|
```ts
|
|
import { Context, Effect, Layer } from "effect";
|
|
|
|
class Database extends Context.Tag("Database")<Database, {
|
|
query: (sql: string) => Effect.Effect<unknown[], DBError>;
|
|
}>() {}
|
|
|
|
const DatabaseLive = Layer.succeed(Database, {
|
|
query: (sql) => Effect.tryPromise({ try: () => pool.query(sql), catch: (e) => new DBError(e) }),
|
|
});
|
|
|
|
const program = Effect.gen(function* () {
|
|
const db = yield* Database;
|
|
const rows = yield* db.query("SELECT * FROM users");
|
|
return rows;
|
|
});
|
|
|
|
Effect.runPromise(program.pipe(Effect.provide(DatabaseLive)));
|
|
```
|
|
|
|
### Schema (Effect's Zod-equivalent)
|
|
```ts
|
|
import { Schema } from "effect";
|
|
|
|
const User = Schema.Struct({
|
|
id: Schema.String.pipe(Schema.brand("UserId")),
|
|
email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+$/), Schema.brand("Email")),
|
|
age: Schema.Number.pipe(Schema.int(), Schema.between(0, 150)),
|
|
});
|
|
|
|
type User = Schema.Schema.Type<typeof User>;
|
|
const decoded = Schema.decodeUnknownSync(User)(input);
|
|
```
|
|
|
|
### 의 Concurrency
|
|
```ts
|
|
import { Effect } from "effect";
|
|
|
|
const fetchAll = Effect.all(
|
|
[fetchUser(u1), fetchUser(u2), fetchUser(u3)],
|
|
{ concurrency: 2 },
|
|
);
|
|
```
|
|
|
|
### 의 Either (sync error)
|
|
```ts
|
|
import { Either } from "effect";
|
|
|
|
const safeParse = (s: string): Either.Either<number, "not_a_number"> => {
|
|
const n = Number(s);
|
|
return Number.isNaN(n) ? Either.left("not_a_number") : Either.right(n);
|
|
};
|
|
```
|
|
|
|
### Effect 의 React (effect-rx)
|
|
```tsx
|
|
import { useRxSuspense } from "@effect-rx/rx-react";
|
|
|
|
const userRx = Rx.make((get) => fetchUser(get(userIdRx)));
|
|
|
|
function UserProfile() {
|
|
const user = useRxSuspense(userRx);
|
|
return <div>{user.email}</div>;
|
|
}
|
|
```
|
|
|
|
## 매 결정 기준
|
|
| 상황 | Approach |
|
|
|---|---|
|
|
| Domain ID 의 의 mix-up 의 prevent | ts-brand 의만 |
|
|
| Validated value (email, URL) | ts-brand 의 + smart constructor |
|
|
| Complex async pipeline | Effect TS |
|
|
| Typed error + retry + timeout | Effect TS |
|
|
| DI 의 의 typed | Effect Layer |
|
|
| Simple fetch + try/catch | 매 plain async — Effect 의 X |
|
|
|
|
**기본값**: ts-brand 의 의 always, Effect 의 의 의 complex pipeline 의만.
|
|
|
|
## 🔗 Graph
|
|
- 부모: [[TypeScript]] · [[Functional Programming]]
|
|
- 변형: [[fp-ts]] · [[ZIO]] · [[neverthrow]]
|
|
- 응용: [[Discriminated Unions for Error Handling]] · [[Dependency Injection]]
|
|
- Adjacent: [[Zod]] · [[Branded Types]] · [[Schema Validation]]
|
|
|
|
## 🤖 LLM 활용
|
|
**언제**: typed pipeline 의 design, domain ID safety, layer-based DI, schema-driven decode.
|
|
**언제 X**: 의 매 simple CRUD — 매 Effect 의 learning curve 의 의 not worth.
|
|
|
|
## ❌ 안티패턴
|
|
- **`as UserId` 의 의 raw string 의 의 cast**: 의 brand 의 의 bypass — 의 smart constructor 의 의 always.
|
|
- **Effect 의 의 entire codebase 의 의 force**: 의 team 의 의 buy-in 의 X 의 시 의 — 매 friction.
|
|
- **`Effect.runSync` 의 의 async 의**: 의 throw 의 의 — runPromise 의 의 사용.
|
|
- **Mutable state 의 의 Effect 의**: 의 referential transparency 의 의 violation — Ref/Layer 의 의 사용.
|
|
- **Brand 의 의 nested 의 reuse**: `Brand<Brand<string, "A">, "B">` 의 의 confusing — 매 single brand 의 keep.
|
|
|
|
## 🧪 검증 / 중복
|
|
- Verified (Effect-TS docs effect.website, ts-brand npm, ZIO inspiration, Effect Schema docs).
|
|
- 신뢰도 A.
|
|
|
|
## 🕓 Changelog
|
|
| 날짜 | 변경 |
|
|
|---|---|
|
|
| 2026-05-08 | Phase 1 |
|
|
| 2026-05-10 | Manual cleanup — Effect.gen + Layer + Schema + ts-brand smart constructor 추가 |
|