기초 및 개념 이해

React와 TypeScript

타입 시스템 심화 및 패턴

성능 및 효율적인 코드 작성

스타일 가이드 및 실전 활용

Node.js 및 빌드 관련

함수형 프로그래밍과 TypeScript

마이그레이션 사례


Footnotes

  1. Chrome DevTools 및 Puppeteer를 TypeScript로 마이그레이션한 경험에 대한 설명 ↩

  2. 대규모 JavaScript 코드베이스를 TypeScript로 자동 마이그레이션하는 도구인 “ts-migrate”를 소개하는 Airbnb 엔지니어링 팀의 블로그 게시물 ↩

  3. Flow에서 TypeScript로 마이그레이션한 경험을 설명하고 오픈소스 flow-to-typescript-codemod 도구에 대한 링크를 포함하는 Stripe 엔지니어링 팀의 블로그 게시물 ↩

  4. Etsy 엔지니어링 팀이 대규모 웹 애플리케이션에서 TypeScript를 채택한 방법, 직면한 문제 및 얻은 이점을 설명 ↩

#13

interface 안에 이름 없는 (a, b) => 반환 형태의 호출 시그니처를 두면 그 인터페이스가 함수 타입이 된다. const sum: MathFn = (a, b) => a + b 처럼 변수에 타입을 붙이면 매개변수 a·b 의 타입은 문맥에서 추론된다.

-- interface 의 호출 시그니처 = 함수 타입
type MathFn = Double -> Double -> Double      -- interface MathFn { (a: number, b: number): number }

sum :: MathFn
sum a b = a + b                                -- const sum: MathFn = (a, b) => a + b — a·b 는 문맥에서 추론
#15

acorn 을 acorn-jsx 로 확장한 파서로 파일을 모듈로 파싱하고, 나온 AST 에 JSXIdentifier 노드가 하나라도 있으면 JSX 를 쓰는 파일로 본다. CRA 에서 Vite 로 옮길 때 .js 를 .jsx 로 바꿀 파일을 고르는 데 쓴다.

-- 이 .js 가 JSX 를 쓰나 (CRA → Vite 로 옮길 때 .jsx 로 바꿀 파일 고르기)
isReactComponent :: String -> Bool
isReactComponent = any isJSXIdentifier . universe   -- AST 어딘가에 JSXIdentifier 가 있나
                 . parseJSX Module Latest          -- acorn.Parser.extend(acorn-jsx)
#255

Year 의 year 는 인자 없이 부르면 number, 문자열을 주면 string 인 오버로드다. T extends R 은 R 처럼 불렀을 때 T 의 시그니처 중 하나라도 받아내는지를 묻는다 — 받아내려면 R 보다 인자를 더 요구하지 않고, 받는 인자 타입이 맞고, 돌려주는 값이 R 의 반환 자리에 들어가야 한다. 그래서 () => number 와 (u: string) => string 은 둘 다 통과하고, (u: number) => number 도 year() 가 u 를 버리고 받아내 통과한다. 반면 ReturnType 과 infer 는 묻지 않고 마지막 시그니처에서 꺼내서, ReturnType 은 string 이고 () => infer R 은 never 다.

-- T extends R 은 "R 처럼 불러도 T 가 받아내나" — 오버로드면 시그니처 하나만 받아내면 된다
extends :: Overloaded -> Sig -> Bool
t `extends` r = any (`accepts` r) (signatures t)

accepts :: Sig -> Sig -> Bool
sig `accepts` r = arity sig <= arity r              -- 1 더 요구하지 않는다 (남는 인자는 버린다)
               && params r `assignableTo` params sig -- 2 받는 인자 타입이 맞는다
               && ret sig `assignableTo` ret r       -- 3 돌려주는 값이 R 자리에 들어간다

year = [ Sig [] Number, Sig [String] String ]
year `extends` Sig [] Number           == True
year `extends` Sig [String] String     == True
year `extends` Sig [Number] Number     == True    -- year() 가 u 를 버리고 받아낸다

-- infer 는 묻지 않고 꺼낸다: 마지막 시그니처에서. 인자 목록으로 오버로드를 고를 수 없다
returnType year == String                          -- 순서를 바꾸면 Number
(year `extends` Sig [] (Infer r)) == Never         -- r = String 을 꺼낸 뒤 () => String 을 받아내는 시그니처가 없다

-- 직접 정의하면 오버로드 대신 제네릭 하나로
-- year<U extends [] | [string]>(...a: U): U extends [] ? number : string
-- 그러면 ReturnType<typeof y.year<[]>> 로 꺼낸다
#345

RenderPropNames 는 Title | Content | Actions 다. 매핑 타입이 멤버를 하나씩 K 로 돌고, as 가 키 이름을 render${K} 로 바꿔서 renderTitle·renderContent·renderActions 세 prop 이 생긴다. 각각 ReactNode 를 돌려주는 함수다. 이름을 바꾸는 as 는 TS 4.1 부터.

-- 템플릿 리터럴 타입으로 prop 이름을 만든다 (TS 4.1+ key remapping)
type Names = "Title" | "Content" | "Actions"
type RenderProps = { [k in Names as "render" ++ k]: () -> Node }
-- == { renderTitle :: () -> Node, renderContent :: () -> Node, renderActions :: () -> Node }

dialog { renderTitle, renderContent, renderActions } =
  div "root" [ div "content" [renderTitle (), renderContent ()]
             , div "actions" [renderActions ()] ]
#350

JSON 값은 셋 중 하나다. 기본값(string·number·boolean·null), 문자열 키에 JSON 값을 담은 객체, JSON 값의 배열. 객체와 배열이 다시 JSON 값을 담아 재귀한다. type-fest 의 JsonObject 는 선택 속성이 undefined 일 수 있게 한 겹 더 열어 두고, JsonArray 는 readonly 배열도 받는다.

-- JSON 값 = 기본값 | 객체 | 배열, 객체·배열이 다시 JSON 값을 담는다
data JsonPrimitive = JString String | JNumber Double | JBool Bool | JNull
data JsonValue     = Prim JsonPrimitive
                   | Obj (Map String JsonValue)   -- type-fest: 선택 속성은 undefined 도 허용
                   | Arr [JsonValue]              -- readonly 배열도
-- 직렬화 결과 타입까지 필요하면 type-fest 의 Jsonify
#376

생성자는 항상 그 클래스의 새 인스턴스를 돌려준다. 생성자를 private 으로 막고 static create 를 두면 셋을 할 수 있다: 유효성 검사에 실패하면 null(또는 Result)을 돌려주고(이름이 3자 미만이면 null), 인자에 따라 다른 하위 클래스를 돌려주고(circle 이면 Circle, rect 면 Rectangle), 이미 있는 인스턴스를 돌려준다(싱글톤). 단순 초기화만 필요하면 생성자가 더 직관적이다.

-- 생성자는 항상 새 인스턴스를 준다. private 생성자 + static create 면 셋이 된다
create :: String -> Maybe User           -- 1 실패를 값으로 (null / Result)
create name | length name < 3 = Nothing
            | otherwise       = Just (User name)

shape :: Kind -> Size -> Shape           -- 2 하위 클래스를 고른다 (팩토리)
shape Circle = circle
shape Rect   = rectangle

config :: IO Config                      -- 3 같은 인스턴스 (싱글톤): instance ??= new Config()
config = readIORef instanceRef >>= maybe (newConfig >>= cache) pure
-- 단순 초기화만이면 생성자가 더 직관적
#381

Figma 는 흩어진 권한 로직(불필요한 복잡성·계층 권한 비효율·DB 부하·여러 진실 소스)을 JSON 으로 직렬화되는 DSL 로 모았다. 식은 셋뿐이다: [필드, 연산자, 값] 꼴의 이항 식, 그리고 그걸 묶는 and·or. 예: file.id 가 null 이 아니고 team.permission 이 open 이면. 정책이 데이터라 어디로든 보낼 수 있고, TypeScript 평가 엔진이 하나로 판정한다.

-- Figma 권한 DSL: 정책을 JSON 으로 직렬화되는 식으로, 평가는 TypeScript 엔진 하나로
-- (이전: 불필요한 복잡성 · 계층 권한 비효율 · DB 부하 · 여러 진실 소스)
data Expr = Binary Field Op Value   -- ['file.id', '<>', null]
          | And [Expr]              -- { and: [...] }
          | Or  [Expr]              -- { or: [...] }

eval :: Row -> Expr -> Bool
eval r (Binary f op v) = apply op (r ! f) v
eval r (And es)        = all (eval r) es
eval r (Or es)         = any (eval r) es

canView = And [ Binary "file.id" "<>" Null, Binary "team.permission" "=" "open" ]
#382

verbatimModuleSyntax 를 켜면 컴파일러가 import 가 타입으로만 쓰이는지 추측하지 않는다. type 표시가 없는 import 는 출력 JS 에 그대로 남고, type 표시가 있는 것만 통째로 지운다. 그래서 타입만 가져올 땐 import type 으로 적어야 한다 — 안 그러면 런타임에 없는 값을 import 하게 되어 TS1484 에러가 난다. 기존 코드는 fix-verbatim-module-syntax 로 자동으로 고친다.

-- verbatimModuleSyntax: 쓰임새를 추측하지 않고 표시대로만 지운다
emit :: Import -> Maybe Import
emit (Import Type _) = Nothing      -- import type { A } — 통째로 지운다
emit i               = Just i       -- type 없는 import 는 그대로 남는다

-- 그래서 타입만 가져올 땐 표시해야 한다 (안 하면 TS1484)
import type { A } from 'a'
-- 기존 코드 일괄 수정: fix-verbatim-module-syntax
#462

Props<TRow> 와 넘긴 props 를 칸마다 나란히 놓는다. rows: TRow[] 자리에는 { name: string }[] 이 와서 배열 안의 맨몸 TRow 자리에서 { name: string } 을 후보로 줍는다. renderRow 의 row 는 타입을 안 적었으니 주울 게 없다. extends Record<string, any> 는 넘긴 값이 아니라 후보가 아니다. 후보에서 고른 TRow 를 제약에 맞춰 보고, 안 맞으면 TRow 를 제약으로 바꿔 끼운 채 검사해 에러를 낸다. 후보로 TRow = { name: string } 이 정해지면 그 타입이 거꾸로 renderRow 의 row 로 흘러가서 row.name 을 쓸 수 있다.

-- 제네릭 컴포넌트: <TRow extends Record<string, any>> 로 넘긴 rows 에서 row 타입을 줍는다
table :: (row <: Record String Any) => { rows :: [row], renderRow :: row -> Int -> Node } -> Node
table { rows, renderRow } = tbody (zipWith renderRow rows [0..])

-- 1 줍기: 선언(Props<TRow>)과 넘긴 값을 칸마다 나란히 놓고, 맨몸 TRow 자리에서 후보를 줍는다
infer { rows = [{ name = "lee" }] }  -- [TRow] ↔ [{ name :: String }] → 후보 { name :: String }
--   renderRow 의 row 는 타입을 안 적어 주울 게 없다. extends 는 넘긴 값이 아니라 후보가 아니다
--   정해진 TRow 가 거꾸로 renderRow 로 흘러가 row.name 이 된다

-- 2 고르기: 후보가 여럿이면 자리로 — 내주는 쪽(공변)이 받는 쪽(반변)에 들어가면 공변이 이긴다
pick { rows = dogs, renderRow = \(row :: Animal) (i :: Int) -> … } == Dog      -- 다 적음: 함수 타입끼리 비교해 Animal 이 반변 후보, Dog 가 Animal 에 들어가니 공변이 이긴다
pick { rows = dogs, renderRow = \(row :: Animal) -> … }            == Animal   -- 덜 적음: 적힌 타입만 읽어 Animal 을 공변 후보로 넣고, Dog 와의 공통 상위를 고른다
--   화살표 함수 리터럴일 때 얘기다. 이미 만든 함수면 덜 적어도 Dog, function 표현식은 다 적어도 Animal

-- 3 두 번째로 쓰는 자리는 NoInfer 로 줍기에서 뺀다 (TS 5.4+)
type Props row = { rows :: [row], renderRow :: row -> Int -> Node, selectedRow :: Maybe (NoInfer row) }
--   없으면 selectedRow { name, age } 도 후보가 돼 union 으로 넓어지고 에러가 안 난다
--   있으면 selectedRow 는 줍지 않아 TRow = { name } 이 되고, selectedRow 를 그 타입으로 검사하다 age 에서 에러가 난다

-- 4 extends Record<string, any> 는 원시값만 막는다 (= object)
--   Record<string, unknown> 은 type 별칭 객체만 — interface·배열·함수도 막힌다
-- 같은 패턴: downshift Combobox<T> 의 items → renderItem item
#480

{ a: 1 } & { b: 2 } 같은 교차 타입이나 ComponentProps 는 에디터 툴팁에 별칭 이름이나 & 로 이어진 조각으로 보인다. 매핑 타입 { [K in keyof T]: T[K] } 가 속성을 한 객체로 다시 모으고, 거기에 & {} 를 붙여야 별칭 이름 대신 펼친 모양 { a: 1; b: 2 } 이 뜬다. 왜 & {} 가 필요한지는 공식 설명이 없는 컴파일러의 특이점이다.

-- 교차 타입을 한 객체로 펼쳐 보여준다 (에디터 툴팁·에러 메시지용)
type Prettify t = { [k in keyof t]: t ! k } & {}
-- 매핑 타입이 속성을 다시 모은다
-- & {} 가 있어야 별칭 이름(Prettify<…>) 대신 펼친 모양이 뜬다 — & unknown 도 같다
-- 왜 그런지는 공식 설명이 없다: "a quirk of the TypeScript compiler" — Total TypeScript, The Prettify Helper (tsc 5.9.3 에서 확인)

show (Prettify ({ a :: 1 } & { b :: 2 })) == "{ a: 1; b: 2 }"
p :: Prettify (ComponentProps "div")
#481

ModalProps 는 variant 가 no-title 인 것과, variant 가 title 이면서 title 문자열이 있는 것의 유니온이다. if (variant === no-title) 바깥 분기에선 props 가 title 멤버로 좁혀져 props.title 을 쓸 수 있다. variant 없이 쓰면 막히고, no-title 에 title 을 붙여도 막힌다 — 초과 속성 검사가 variant 로 먼저 고른 멤버 하나에 대고 이뤄지기 때문이다. 판별 속성이 없는 유니온은 겹치는 조합을 받는다.

-- 리터럴 공통 속성(variant)으로 유니온을 가른다
data ModalProps = NoTitle                    -- variant: 'no-title'
                | Title { title :: String }  -- variant: 'title'

modal :: ModalProps -> Element
modal NoTitle   = div "No title"
modal (Title t) = div ("Title: " ++ t)       -- 이 분기 안에서 props 는 Title 로 좁혀진다

-- 초과 속성 검사도 variant 로 먼저 고른 멤버 하나에 대고 한다
check { variant = "no-title", title = "Oh dear" }   -- ✗ NoTitle 에 title 없음
check {}                                             -- ✗ variant 없음
-- 판별 속성이 없는 { a :: Int } | { b :: String } 은 { a = 1, b = "x" } 를 받는다 ("partial overlap")
#482

Image 의 src 타입은 Exclude<T, ‘’> 이다. T extends string 제약이 있으면 src=“” 를 넘길 때 T 가 리터럴 ‘’ 로 추론돼 Exclude<‘’, ‘’> 가 never 가 되어 막히고, “ab” 는 그대로 통과한다. 제약을 빼면 T 가 string 으로 넓어져 ‘’ 도 통과한다. 또 string 타입 변수를 넘기면 T = string 이라 Exclude<string, ‘’> 도 string 이어서 값이 ‘’ 여도 통과한다 — 인자 타입이 리터럴 ‘’ 일 때만 막는 가드다.

-- 빈 문자열 src 를 타입으로 막는다
type NonEmptyString t = Exclude t ""
image :: (t <: String) => { src :: NonEmptyString t } -> Element
-- t <: String 제약이 있어야 넘긴 리터럴을 그대로 줍는다 (빼면 t = String 으로 넓어져 "" 도 통과)

infer (image { src = "" })   -- t = "" → Exclude "" "" = never   ✗
infer (image { src = "ab" }) -- t = "ab"                          ✓
infer (image { src = s })    -- s :: String → t = String → String ✓ 값이 "" 여도
-- 인자 타입이 리터럴 "" 일 때만 막는 가드다 (const e: '' = '' 도 막힌다)

-- 왜 리터럴로 남나: 들어갈 자리가 primitive 제약을 가진 타입 변수면 리터럴 문맥으로 본다
#483

O 의 actions 안 b 만 선택 속성으로 바꾸려면, 바깥에서 Omit 으로 actions 를 빼고, 같은 키 actions 를 매핑 타입으로 다시 붙이면서 그 안쪽을 Omit(b) & Partial(Pick(b)) 로 만든다. 결과는 actions 가 { a: string; b?: number }. 덮어쓰기는 안쪽을 Omit(덮을 키) & 새 타입으로. 한두 곳에만 쓸 거면 손으로 쓰는 게 더 명확하다. 값을 바꿀 때도 라이브러리 객체를 직접 고치지 말고 펼쳐서 새로 만든다.

-- 중첩 객체 타입의 안쪽만 바꾼다: 바깥에서 K 를 빼고, 같은 키로 다시 붙이며 안쪽을 고친다
type NestedOptional t k ok = Omit t k & { k :: Omit (t ! k) ok & Partial (Pick (t ! k) ok) }
type OverrideNested t k o  = Omit t k & { k :: Omit (t ! k) (keyof o) & o }

type O = { actions :: { a :: String, b :: Number } }
NestedOptional O "actions" "b"          == { actions :: { a :: String, b :: Maybe Number } }
OverrideNested O "actions" { b :: Bool } == { actions :: { a :: String, b :: Bool } }

-- 한두 곳이면 손으로 쓰는 게 더 명확하다. 반복될 때만 유틸리티
-- 값도 같은 방식으로: 라이브러리 객체를 변이하지 말고 펼쳐서 새로
modified = info { actions = (actions info) { onDownload = Nothing } }
#499

SelectProps 의 T 는 single 또는 multiple 이고 기본값은 multiple 이다. SelectProps 라고만 쓰면 T 가 multiple 로 정해져 value 가 string[] 이 되고, SelectProps<single> 로 명시하면 value 가 string 이 된다. 기본값은 제약(single | multiple)을 만족해야 한다. 가장 자주 쓰는 경우를 기본값으로 두면 매번 제네릭을 적지 않아도 된다.

-- 제네릭 기본값: <T extends Type = Default>. 생략하면 기본값, 기본값은 제약을 만족해야 한다
type Mode = 'single' | 'multiple'
type SelectProps (t :: Mode = 'Multiple') = { mode :: t, value :: Value t }

type family Value t where
  Value 'Single   = String
  Value 'Multiple = [String]

a :: SelectProps                  -- t = 'Multiple
a = { mode = Multiple, value = ["a", "b"] }
b :: SelectProps 'Single
b = { mode = Single, value = "a" }

-- 매개변수마다 기본값
type ApiResponse (d = Any) (s :: Status = 'Loading) = { data' :: If (s == 'Success) d Null, status :: s }
-- 가장 자주 쓰는 경우를 기본값으로 — 매번 적지 않는다
#516

판별 유니온 Button 은 type 이 submit 이면 color 가, reset 이면 text 가 있다. 코드에서는 type 을 보는 순간 나머지 속성이 정해져 타입 검사와 자동완성이 된다. 그런데 속성 표로 문서화하면 속성마다 한 줄이라 color·text 의 조건을 “type 이 무엇일 때 필수” 라는 글로 적어야 하고, 갈래가 늘면 표가 복잡해진다. 표는 속성 중심, 유니온은 갈래 중심이라 모양이 맞지 않는다. typedoc·api-extractor 로 타입에서 문서를 생성하는 쪽이 낫다.

-- 판별 유니온은 코드엔 좋은데 문서로 옮기기 어렵다
data Button = Submit { color :: String }   -- type: 'submit'
            | Reset  { text  :: String }   -- type: 'reset'
-- 코드: 갈래마다 묶여 있다 — type 을 보면 나머지가 정해진다 (타입 검사·자동완성)

-- 문서 표: 속성마다 한 줄이라 갈래가 조건 문장으로 풀린다
docs = [ ("type",  "'submit' | 'reset'", "필수")
       , ("color", "string", "type = 'submit' 일 때 필수")
       , ("text",  "string", "type = 'reset' 일 때 필수") ]   -- 갈래가 늘면 표가 복잡해진다

-- 그래서 정의 파일을 원본으로 두고 생성한다: typedoc · api-extractor
#524

Redux 스타일 store 는 상태 하나와 리스너 목록 하나다. dispatch(action) 은 reducer(지금 상태, action) 으로 새 상태를 만들어 갈아 끼우고, 리스너 전부에게 새 상태를 알린 뒤 action 을 돌려준다. subscribe 는 리스너를 곧바로 지금 상태로 한 번 부르고 목록에 넣으며, 목록에서 빼는 함수를 돌려준다. getState 는 지금 상태를 읽는다.

-- 간단한 Redux 스타일 store: 상태 하나 + 리스너 목록 하나
createStore :: (s -> a -> s) -> s -> Store s a
createStore reducer s0 = Store { getState, subscribe, dispatch }   -- s0: 만들 때 리듀서와 함께 넘기는 초기 상태 (preloadedState)
  where
    getState      = read state
    dispatch a    = do s' <- reducer <$> read state <*> pure a
                       state := s'
                       mapM_ ($ s') =<< read listeners
                       pure a
    subscribe l   = do l =<< read state          -- 지금 상태로 한 번 곧바로
                       listeners %= (l :)
                       pure (listeners %= filter (/= l))   -- 해지 함수
#529

null 일 수 있는 단계를 잇는다: 스크롤 요소 → 그 안의 #id 요소 → 첫 사각형 → scrollLeft 를 그 left 로. 어느 단계든 null 이 나오면 뒤 단계는 부르지 않고 null 로 끝난다. Maybe 의 map 으로 쓰면 체인 하나, generator 로 쓰면 단계마다 if (!x) return 으로 일찍 빠져나간다 — 같은 모양이다.

-- null 일 수 있는 단계를 체크 없이 잇는다
fmap :: (a -> b) -> Maybe a -> Maybe b
fmap f (Just x) = ofNullable (f x)   -- 결과가 null 이면 Nothing 으로
fmap _ Nothing  = Nothing            -- 뒤 단계는 부르지 않는다

scrollTo id = ofNullable scrollElement
  >>= querySelector ("#" ++ id)
  >>= (listToMaybe . getClientRects)
  <&> \rect -> root.scrollLeft := left rect

-- generator 로 쓰면 같은 모양의 early return
handleScroll id = do
  root   <- scrollElement   -- if (!root) return
  target <- querySelector ("#" ++ id) root   -- if (!target) return
  yield (maybe 0 left (listToMaybe (getClientRects target)))
#533

Just 10 에 bind 로 safeDivide _ 2 를 이으면 Just 5 가 된다. safeDivide _ 0 을 이으면 0 으로 나눌 수 없어 Nothing 이 되고, 그 뒤에 무엇을 bind 해도 함수를 부르지 않고 Nothing 이 그대로 흐른다. 중간마다 null 검사를 쓰지 않아도 실패가 끝까지 전파된다.

-- TypeScript 로 Maybe 를 만든다: Just·Nothing 두 클래스에 bind 하나씩
data Maybe a = Just a | Nothing

bind :: Maybe a -> (a -> Maybe b) -> Maybe b
bind (Just x) f = f x        -- class Just    { bind(fn) { return fn(this.value) } }
bind Nothing  _ = Nothing    -- class Nothing { bind(fn) { return this } } — fn 을 안 부른다

safeDivide :: Double -> Double -> Maybe Double
safeDivide _ 0 = Nothing
safeDivide x y = Just (x / y)

Just 10 `bind` (`safeDivide` 2) == Just 5
Just 10 `bind` (`safeDivide` 0) == Nothing
#535

useGenerator 의 상태는 useReducer 하나다. idle 에서 start 로 running 이 되고(에러도 함께 비운다), yield 는 status 를 두고 value 만 바꾸며, generator 가 끝나면 done, 본문 어디서든 throw 하면 catch 에서 error 로 errored 다. cancel 은 abort 하고 idle 로 되돌린다 — 안 하면 running 에 멈춘다. unmount 되면 cleanup 이 abort 하고, 기다리던 await wait 가 reject 돼 throw 가 나지만 aborted 라 에러로 치지 않는다. 같은 훅을 쓰는 쪽이 재진입 정책을 고른다: LoadingButton 은 running 동안 disabled 로 다시 못 누르게 하고 JSX 를 yield 하면 그대로 라벨이 된다. 검색은 run(q) 마다 직전 실행을 abort 하고 다시 시작해, a 다음 ab 를 치면 a 의 remote 결과가 끼어들지 않는다.

-- isLoading 없이 onClick 에서 yield 만 한다 — 시간이 코드의 한 방향(↓)으로만 흐를 때
--   멀티 단계 loading · progressive search · optimistic mutation(optimistic | reconciled | rolledBack)
data Status  = Idle | Running | Errored | Done
data Event a = Start | Yield a | Finish | Throw Error | Cancel

step :: State a -> Event a -> State a
step s Start     = s { status = Running, error = Nothing }   -- 상태와 에러 초기화가 한 번에 — 따로 set 하다 어긋날 일이 없다
step s (Yield v) = s { value = v }                           -- status 는 두고 값만
step s Finish    = s { status = Done }
step s (Throw e) = s { status = Errored, error = Just e }
step s Cancel    = s { status = Idle }                       -- 없으면 Running 에 멈춘다

-- 핸들러는 값의 흐름(async generator), 훅은 그걸 접는다
state = foldl step initial (run fn args)

run :: (Signal -> args -> Stream a) -> args -> [Event a]
run fn args = Start : map Yield (untilAborted (fn signal args)) ++ end
  where end | aborted   = []          -- abort 로 생긴 throw 는 에러가 아니다
            | otherwise = [Finish]    -- 본문 어디서 throw 하든 Throw e
-- run 은 직전 실행을 abort 하고 다시 시작한다 · unmount 도 abort

-- 재진입 정책은 쓰는 쪽이 고른다
--   버튼: Running 동안 disabled, yield 한 JSX 가 곧 라벨
--   검색: run 마다 재시작 — tier 경계(await wait)가 곧 취소 지점이라 debounce 가 필요 없다
searchTiers q = do wait 100; yield [q ++ ":local"]
                   wait 300; yield [q ++ ":local", q ++ ":remote"]

-- 확인: a 를 치고 150ms 에 ab
shown == [["a:local"], ["ab:local"], ["ab:local", "ab:remote"]]   -- a:remote 는 끼어들지 않는다
#540

흩어진 호출 지점이 모두 lookup 하나를 거쳐 배열 참조로 캐시를 찾는다. 같은 참조면 인덱스를 재사용하고, refetch 로 새 참조가 오면 한 번 다시 빌드하며 옛 entry 는 GC 된다. push 처럼 제자리에서 바꾸면 참조가 같아 옛 인덱스가 나온다. 매번 새 배열을 넘기면 항상 miss 다.

-- 같은 배열을 이름으로 반복 조회해 O(n) 스캔이 계속 도는데, 배열이 언제 바뀌는지 추적하기 싫을 때
-- 캐시 키를 배열의 내용이 아니라 참조로 둔다 — 무효화를 참조 동등성에 맡긴다
lookup :: Ref [Item] -> Name -> Cache -> (Maybe Id, Cache)
lookup items name cache = case WeakMap.get items cache of
  Just index -> (Map.lookup name index, cache)                 -- 여기부터 O(1)
  Nothing    -> let index = buildIndex (deref items)            -- 새 참조면 자동 miss, 한 번 O(n)
                in  (Map.lookup name index, WeakMap.set items index cache)
-- delete·clear 가 어디에도 없다: 불변 업데이트면 "데이터가 바뀜" = "참조가 바뀜"
-- 키가 weak 이라 옛 items 가 안 잡히면 entry 도 GC 된다. Map 이면 영구히 붙들려 누수

-- 결과는 참조만 보고 정해진다 — 내용은 보지 않는다
outcome :: SameRef -> SameContent -> Outcome
outcome True  True  = Hit
outcome False False = Rebuild   -- refetch. 옛 인덱스는 옛 배열과 함께 GC
outcome False True  = Miss      -- 매번 [...data]·data.filter() 로 넘긴다 — 무의미
outcome True  False = Wrong     -- push·splice 로 제자리에서 바꿨다 — 느린 게 아니라 틀린 값
-- TanStack Query 의 data·select 결과는 참조가 안정적이라 그대로 넘기면 된다

-- 된 것: 같은 참조로 두 번 불러 buildIndex 가 한 번만 돈다

허용 표기를 as const 배열 하나에 두고, 거기서 닫힌 union 타입 DateFormat 을 파생해, 유일한 진입점 formatDate 의 인자로 쓴다. 이름과 포맷을 짝짓는 매핑 객체는 필요 없다 — dayjs 는 포맷 문자열이 곧 키이자 값이다. 새 표기는 여러 화면에서 통일이 필요할 때만 배열에 넣고, 일회성이면 raw dayjs().format 으로 둔다. 구멍이 둘 있다: raw 로 우회해도 타입이 못 막고, ddd 는 locale(‘ko’) 없이 쓰면 Mon·Tue 로 경고 없이 나온다.

-- 화면마다 dayjs().format('…') 이 흩어져 같은 날짜가 다르게 찍힌다: 허용 표기를 타입으로 닫는다
-- 매핑 객체({ DATE: 'YYYY-MM-DD', … })는 i18n 습관이다 — i18n 은 이름표(인사)와 내용(Hello)이 달라서 짝짓기가 필수였다
-- dayjs 는 포맷 문자열이 곧 키이자 값 — 이름을 붙인 매핑 객체는 같은 정보를 두 번 든다
formats :: [Format]                                   -- 단일 출처 (DATE_FORMATS as const)
formats = [ "YYYY-MM-DD", "YYYY-MM-DDTHH:mm:ss", "HH:mm", "YYYY년 M월", "YY년 M월 D일"
          , "YYYY.MM.DD", "YY.MM.DD", "YYYY.MM.DD(ddd)", "YYYY.MM.DD HH:mm" ]

type DateFormat = { f :: Format | f ∈ formats }       -- 배열에서 파생된 닫힌 union, 따로 손댈 곳 없음

formatDate :: Date -> DateFormat -> String            -- 유일한 진입점
formatDate d f = format (dayjs d) f

-- 새 표기는 여러 화면에서 통일이 필요할 때만 formats 에 넣는다. 일회성('M.D')은 raw 로
-- 이 기준이 없으면 배열이 잡동사니 enum 이 된다

-- 구멍: raw 우회는 타입이 못 막는다 (no-restricted-syntax 규칙 전까지 단일 출처는 관행)
-- 구멍: "ddd" 는 locale "ko" 없이 Mon·Tue 로 조용히 샌다 — 런타임 전제를 가진 유일한 항목
#576

transform 은 CSS 를 네 단계로 TypeScript 모듈로 바꾼다. 먼저 파싱하고, 문법 오류가 있으면 진단을 남긴 뒤 관대한 파서로 다시 읽는다. 다음으로 내보낼 이름(클래스, id, keyframes, @value, :export 키)을 모으면서 CSS 에 적힌 위치를 같이 적는다. 그다음 이름을 설정에 따라 camelCase 같은 키로 바꾼다. 마지막으로 TypeScript 를 써 내려가면서, 키를 하나 쓸 때마다 그 자리를 원본 CSS 의 이름 자리에 잇는 대응 한 칸을 남긴다. 키와 원본 이름의 글자가 달라도 hover 와 정의로 가기는 CSS 의 그 이름으로 간다.

-- TS 7 content mapper 가 transform 요청을 받으면: CSS 모듈 → TS 모듈 + 대응표 + 진단
transform :: Options -> Content -> Result
transform opts = stripBom >>> parse >>> collectLocals >>> exportsOf (localsConvention opts)
             >>> render opts >>> shiftBom
  -- BOM: postcss 가 떼므로 그만큼 원본 위치·진단 위치를 다시 민다

-- ① 오타 하나가 이 파일을 import 하는 모든 곳을 깨지 않게
parse :: CSS -> (Root, [Diagnostic])
parse css = case postcss css of
  Right root -> (root, [])
  Left err   -> (safeParse css, [syntaxError err])   -- 진단을 남기고 살릴 수 있는 만큼 살린다

-- ② 내보낼 이름과, CSS 에 적힌 그 이름의 위치 (escape 포함) — 이 위치가 ④의 대응 끝점이다
locals :: Node -> [Local]
locals (Rule ":export" decls)       = map prop decls          -- ICSS: 키 그대로
locals (Rule sel) | inKeyframes     = []                      -- from·to·50% 는 이름이 아니다
                  | otherwise       = classesAndIds sel       -- :global(…) 안은 빼고, 인자 없는 :global 은 뒤쪽 전부를 뺀다
locals (AtRule "keyframes" name)    = [name]                  -- :global 이면 없음
locals (AtRule "value" params)      = valueNames params       -- @value a: …  /  @value a, b as c from "…"
locals (AtRule "scope" params)      = parenthesized params >>= classesAndIds   -- @scope (.card) to (.content)
locals (Decl "composes" v)          = []                      -- 대신 검사: 이 파일에 없는 클래스면 진단, from 이 붙으면 건너뜀
  -- 같은 이름은 처음 것만. hover 문서 = 앞의 /** */ 주석 + 선언 CSS (12줄까지)

-- ③ 이름 → 키. Vite 의 css.modules.localsConvention 과 같은 값
keys :: Convention -> Name -> [Key]
keys CamelCase     n = [n, camelCase n]          -- camelCase = lodash.camelcase (postcss-modules 와 같게)
keys CamelCaseOnly n = [camelCase n]
keys Dashes        n = [n, dashesCamelCase n]    -- 대시 뒤 글자만 대문자로
keys DashesOnly    n = [dashesCamelCase n]
keys _             n = [n]

-- ④ TS 를 써 내려가다 키를 쓰는 순간, 그 자리를 원본 이름 자리에 잇는다
emitKey :: Key -> Local -> Writer (Text, [SpanMapping]) ()
emitKey key local = do
  here <- length <$> text
  tell ( key
       , [(here, length key, start local, length local, Alias, Hover .|. Definition .|. References .|. DocumentHighlights)] )
  -- Alias: 키(btnPrimary)와 원본(btn-primary)이 달라도 에러·정의로 가기는 원본 이름에 붙는다

render :: Options -> [(Key, Local)] -> (Text, [SpanMapping])
render opts exports =
     [ "declare const styles: { readonly " <> emitKey k l <> ": string; … }; export default styles;" | defaultExport opts ]
                                                     -- 식별자가 아닌 키는 "btn-primary" 문자열 키로
                                                     -- styles 라는 키가 있으면 바인딩을 _styles 로
  <> [ "export declare const " <> emitKey k l <> ": string;" | namedExports opts, isBindingName k ]
                                                     -- 식별자이고 예약어가 아닐 때만
  `orElse` "export {};"                              -- 내보낼 게 없어도 모듈이어야 한다
#603