Skip to content

Latest commit

 

History

History
275 lines (203 loc) · 8.51 KB

README_KO.md

File metadata and controls

275 lines (203 loc) · 8.51 KB

@kakasoo/deep-strict-types

npm version License: ISC TypeScript

깊게 중첩된 TypeScript 객체와 배열을 위한 타입 안전한 Pick, Omit, 키 추출 유틸리티.

English

example

AI 시대에 왜 필요한가?

AI가 그 어느 때보다 많은 코드를 작성하고 있으며, 그만큼 미묘한 실수도 더 많이 발생합니다. 이 라이브러리는 AI가 생성한 코드의 컴파일 타임 가드레일 역할을 합니다.

문제

AI 코딩 도구는 겉보기에는 정상이지만 깊게 중첩된 구조에서 미묘한 타입 불일치가 있는 코드를 자주 생성합니다:

// AI 생성 코드: 괜찮아 보이지만, "prce"는 오타
function getTotal(order: Order) {
  return order.items.map(i => i.prce); // 느슨한 타입에서는 에러 없음
}

해결

엄격한 deep 타입을 제약 조건으로 사용하면, TypeScript 컴파일러가 AI의 실수를 즉시 잡아냅니다:

import { DeepStrictPick } from '@kakasoo/deep-strict-types';

type OrderSummary = DeepStrictPick<Order, 'items[*].price' | 'customer.name'>;

// AI가 정확한 에러를 받음:
// Type '"items[*].prce"' is not assignable to
//   type '"items" | "items[*]" | "items[*].price" | "customer" | "customer.name"'

AI 자체 수정 루프

tsc나 tsx 빌드 루프에서 사용하면, AI 에이전트가 타입 에러를 읽고 무엇이 잘못되었는지 정확히 파악하여 자동으로 수정할 수 있습니다:

AI 코드 생성 → tsc 컴파일 → 타입 에러 → AI가 에러 해석 → AI 자체 수정 → 재컴파일

타입이 엄격할수록 에러 메시지가 정확해지고, AI가 올바른 코드에 더 빠르게 도달합니다. AI 주도 워크플로에서 deep strict 타입은 부담이 아니라 안전망입니다.

설치

npm install @kakasoo/deep-strict-types

빠른 시작

import { DeepStrictObjectKeys, DeepStrictPick, DeepStrictOmit } from '@kakasoo/deep-strict-types';

type User = {
  id: string;
  profile: {
    name: string;
    age: number;
  };
  posts: {
    title: string;
    tags: string[];
  }[];
};

// 모든 중첩 키 경로 추출
type Keys = DeepStrictObjectKeys<User>;
// "id" | "profile" | "profile.name" | "profile.age" | "posts" | "posts[*].title" | "posts[*].tags"

// 원하는 키만 선택
type NameOnly = DeepStrictPick<User, 'profile.name'>;
// { profile: { name: string } }

// 필요 없는 키 제거
type NoAge = DeepStrictOmit<User, 'profile.age'>;
// { id: string; profile: { name: string }; posts: { title: string; tags: string[] }[] }

핵심 타입

DeepStrictObjectKeys<T>

중첩 객체의 모든 키를 dot 표기법 문자열 유니온으로 추출합니다. 배열은 [*] 표기법을 사용합니다.

type Example = {
  user: {
    name: string;
    address: { city: string; zip: number };
  };
};

type Keys = DeepStrictObjectKeys<Example>;
// "user" | "user.name" | "user.address" | "user.address.city" | "user.address.zip"
type WithArray = { items: { name: string; price: number }[] };

type Keys = DeepStrictObjectKeys<WithArray>;
// "items" | "items[*].name" | "items[*].price"

DeepStrictPick<T, K>

지정한 중첩 키만 선택하여 새 타입을 생성합니다. 객체 구조를 그대로 유지합니다.

type Example = {
  user: {
    id: string;
    profile: { name: string; age: number; email: string };
    posts: { title: string; content: string; meta: { likes: number; shares: number } }[];
  };
};

type Picked = DeepStrictPick<Example, 'user.profile.name' | 'user.posts[*].meta.likes'>;
/*
  {
    user: {
      profile: { name: string };
      posts: { meta: { likes: number } }[];
    };
  }
*/

DeepStrictOmit<T, K>

지정한 중첩 키를 제거하여 새 타입을 생성합니다.

type Omitted = DeepStrictOmit<Example, 'user.profile.email' | 'user.posts[*].meta.shares'>;
/*
  {
    user: {
      id: string;
      profile: { name: string; age: number };
      posts: { title: string; content: string; meta: { likes: number } }[];
    };
  }
*/

DeepStrictMerge<Target, Source>

두 객체 타입을 깊게 병합합니다. 동일한 키가 있을 경우 Target이 우선합니다.

type A = { user: { id: string; profile: { name: string } } };
type B = { user: { profile: { email: string }; settings: { theme: string } } };

type Merged = DeepStrictMerge<A, B>;
/*
  {
    user: {
      id: string;
      profile: { name: string; email: string };
      settings: { theme: string };
    };
  }
*/

배열 내 객체도 요소 단위로 병합됩니다:

type Merged = DeepStrictMerge<{ a: number }[], { b: string }[]>;
// { a: number; b: string }[]

GetType<T, K>

특정 중첩 경로의 타입을 추출합니다.

type Data = {
  user: {
    name: string;
    posts: { title: string; tags: string[] }[];
  };
};

type T1 = GetType<Data, 'user.name'>;           // string
type T2 = GetType<Data, 'user.posts'>;           // { title: string; tags: string[] }[]
type T3 = GetType<Data, 'user.posts[*].title'>;  // string
type T4 = GetType<Data, 'user.posts[*].tags'>;   // string[]

DeepDateToString<T>

모든 Date 타입을 재귀적으로 string으로 변환합니다. 직렬화/JSON 응답 타입 표현에 유용합니다.

type Input = {
  createdAt: Date;
  user: { name: string; birthDate: Date };
};

type Output = DeepDateToString<Input>;
// { createdAt: string; user: { name: string; birthDate: string } }

DeepStrictUnbrand<T>

브랜딩 타입(예: typia의 Format<'uuid'> 태그)을 재귀적으로 제거하여 기본 프리미티브 타입으로 복원합니다.

type Branded = {
  id: string & { __brand: 'uuid' };
  profile: { email: string & { __brand: 'email' } };
};

type Clean = DeepStrictUnbrand<Branded>;
// { id: string; profile: { email: string } }

런타임 함수

deepStrictObjectKeys(obj)

DeepStrictObjectKeys의 런타임 버전입니다. 모든 dot 표기법 키 경로를 배열로 반환합니다.

import { deepStrictObjectKeys } from '@kakasoo/deep-strict-types';

const keys = deepStrictObjectKeys({ a: { b: 1, c: 2 } });
// ["a", "a.b", "a.c"]

deepStrictAssert(obj)(key)

특정 중첩 프로퍼티를 추출하는 커링 런타임 함수입니다. 객체 구조를 유지하며, DeepStrictPick의 런타임 버전입니다.

import { deepStrictAssert } from '@kakasoo/deep-strict-types';

const data = {
  user: { name: 'Alice', age: 30 },
  posts: [{ title: 'Hello', content: 'World' }],
};

const result = deepStrictAssert(data)('user.name');
// { user: { name: 'Alice' } }

유틸리티 타입

타입 설명 예시
DeepStrictObjectLastKeys<T> 리프 레벨(최하위) 키만 추출 "a.b.c" ("a" | "a.b" | "a.b.c" 대신)
StringToDeepObject<T> 콤마 구분 dot 표기법 문자열을 중첩 객체 타입으로 변환 StringToDeepObject<"a.b,c"> = { a: { b: any }; c: any }
Equal<X, Y> 타입 레벨 동등성 검사 (true 또는 false 반환) Equal<string, string> = true
ElementOf<T> 배열의 요소 타입 추출 ElementOf<string[]> = string
IsAny<T> any 타입인지 확인 IsAny<any> = true
IsUnion<T> 유니온 타입인지 확인 IsUnion<string | number> = true
ValueType 모든 프리미티브 타입 + Date의 유니온 string | number | boolean | ...
GetMember<T, Prefix> dot 표기법 접두사 이후의 키 세그먼트 추출 DeepStrictOmit 내부 헬퍼
GetElementMember<T, Prefix> [*] 접두사 이후의 배열 요소 하위 키 추출 DeepStrictOmit 내부 헬퍼
RemoveAfterDot<T, K> 하위 키에 대한 와일드카드 패턴 생성 DeepStrictPick 내부 헬퍼
RemoveArraySymbol<T> 키 문자열에서 [*] 접미사 제거 RemoveArraySymbol<"items[*]"> = "items"
RemoveLastProperty<T> 모든 상위 경로 세그먼트 추출 RemoveLastProperty<"a.b.c"> = "a" | "a.b"

라이선스

ISC