kokotable 0.95.0

package/dist/core/src/index.js

@@ -0,0 +1,43 @@
+export * from "./types";
+export * from "./defaults";
+export * from "./utils/getValue";
+export * from "./utils/compare";
+export * from "./filters/text";
+export * from "./filters/number";
+export * from "./filters/date";
+export * from "./filters/list";
+export * from "./filters/relation";
+export * from "./filters/linear";
+export * from "./filters/schedule";
+export * from "./filters/registry";
+// ── 필터 kind ──
+export * from "./filters/kind";
+export * from "./filters/kinds";
+export * from "./filters/describe";
+export * from "./filters/codec";
+export { formatLocalDate, toDateOnly, ISO_DATETIME } from "./utils/dateText";
+export * from "./client/runClientQuery";
+export * from "./client/aggregate";
+export * from "./client/groupRows";
+export * from "./types/grouping";
+export * from "./pivot/transforms";
+export * from "./pivot/runClientPivot";
+export * from "./adapters/sources";
+export * from "./columns/deriveOperators";
+export * from "./columns/labels";
+export * from "./columns/cascade";
+export * from "./columns/ColumnBuilder";
+export * from "./columns/expandSorting";
+export { createColumnHelper, } from "./columns/helper";
+export * from "./hooks";
+export * from "./contracts";
+// ── 검색 debounce·프리셋 ──
+export { createLocalStoragePresetStore, createMemoryPresetStore, loadDefaultPreset, newPresetId, } from "./contracts/presetStore";
+export { usePresets, } from "./contracts/usePresets";
+// ── 테이블 정의 ──
+export * from "./types/definition";
+export * from "./hooks/useTableFromDefinition";
+// ── 레지스트리 ──
+export * from "./registry";
+// ── 백엔드 계약 ──
+export * from "./contract";

package/dist/core/src/pivot/runClientPivot.d.ts

@@ -0,0 +1,101 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import { type LabelResolver } from "../columns/labels";
+import { type AggregationDef } from "../client/aggregate";
+import type { Registry } from "../registry";
+import { type ColumnTransform } from "./transforms";
+/** 피벗 집계 함수 — 백엔드 `AggFunc` 와 같은 이름(대문자) */
+export type PivotAggFunc = "SUM" | "COUNT" | "AVG" | "MIN" | "MAX" | "COUNT_DISTINCT";
+/** 컬럼 타입별 사용 가능한 집계 — 백엔드 `COLUMN_TYPE_AGG_FUNCS` */
+export declare const AGG_FUNCS_BY_TYPE: Record<string, PivotAggFunc[]>;
+export interface PivotColumnSpec {
+    source: string;
+    transform?: ColumnTransform;
+    alias?: string;
+}
+export interface PivotValueSpec {
+    agg: PivotAggFunc;
+    source: string;
+    alias?: string;
+}
+export type HavingOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+export interface PivotHaving {
+    agg: PivotAggFunc;
+    source: string;
+    operator: HavingOperator;
+    value: number;
+}
+export interface PivotSpec {
+    /**
+     * 정확히 2 개의 **동등한** 축. `axes[0]` 이 행 자리, `axes[1]` 이 열 자리다.
+     * transpose 는 두 축을 swap 하면 되므로 별도 옵션이 없다.
+     */
+    axes: [PivotColumnSpec[], PivotColumnSpec[]];
+    values: PivotValueSpec[];
+    having?: PivotHaving[];
+    /** 열 축 leaf 의 distinct 값 상한 — 초과분은 버린다 (성능·UI 보호) */
+    maxPivotValues?: number;
+}
+export interface PivotAxisNode {
+    key: string;
+    label: string;
+    value: unknown;
+    source: string;
+    depth: number;
+    children?: PivotAxisNode[];
+}
+export interface PivotRowNode extends PivotAxisNode {
+    /** 열 leaf 키 → 값 키 → 집계값 */
+    cells: Record<string, Record<string, unknown>>;
+    /** 이 행 전체(모든 열)의 집계 */
+    total: Record<string, unknown>;
+    /** 이 행에 속한 원본 행 수 */
+    count: number;
+    children?: PivotRowNode[];
+}
+export interface PivotResult {
+    rows: PivotRowNode[];
+    /** 중첩 열 헤더 */
+    columns: PivotAxisNode[];
+    /** 열 leaf 키 (화면 왼→오 순서) */
+    leafKeys: string[];
+    /** leaf 키 → 라벨 경로 */
+    leafLabels: Record<string, string[]>;
+    /** 값 키 목록 (`source_AGG` 또는 alias) */
+    valueKeys: string[];
+    /** 전체 총계 */
+    grandTotal: Record<string, unknown>;
+    /**
+     * 열 합계 — 열 leaf 키 → 값 키 → 집계값. 행 `total`·`grandTotal` 과 같은 규칙으로
+     * **원본 행 기준**으로 계산한다 (행별 셀 값을 다시 집계하지 않는다 — AVG 를 셀
+     * 평균의 평균으로 내면 가중치가 사라진다). 원본 행이 없는 열은 키가 없다.
+     */
+    colTotals: Record<string, Record<string, unknown>>;
+    /** `maxPivotValues` 로 잘려나간 열 leaf 수 — 0 이 아니면 화면에 알려야 한다 */
+    droppedColumns: number;
+}
+export interface PivotOptions<T extends RowData> {
+    /**
+     * 축 라벨을 찾을 컬럼 정의.
+     *
+     * CommonCode 축은 셀에 idx 가 들어 있어서 그대로 쓰면 "완료" 대신 "3" 이 뜬다.
+     * 그룹핑(`groupRows`)과 **같은 해석기**를 쓴다 — 둘이 다르면 같은 컬럼이
+     * 그룹 헤더에서는 이름으로, 피벗 축에서는 숫자로 나온다.
+     */
+    columns?: TableColumnDefs<T>;
+    /** 직접 지정하는 라벨 해석기. 주면 `columns` 보다 우선한다 */
+    labelOf?: LabelResolver;
+    /** 집계 레지스트리 — 미지정 시 전역 `aggregations`. 피벗 함수(`SUM` 등)는 같은 id 의 정의로 계산한다 */
+    aggregations?: Registry<AggregationDef>;
+}
+export declare const PIVOT_SEPARATOR = "|";
+export declare function valueKeyOf(spec: PivotValueSpec): string;
+export declare function axisKeyOf(spec: PivotColumnSpec): string;
+/**
+ * 클라이언트 피벗 — 백엔드 `PivotBuilder` 와 같은 계약으로 계산한다.
+ *
+ * 두 축은 **동등**하다. 행/열 전환은 `axes` 를 뒤집으면 되고 별도 경로가 없다.
+ */
+export declare function runClientPivot<T extends RowData>(rows: T[], spec: PivotSpec, options?: PivotOptions<T>): PivotResult;
+/** 행/열 축 전환 — 두 축이 동등하므로 swap 이면 끝난다 */
+export declare function transposePivot(spec: PivotSpec): PivotSpec;

package/dist/core/src/pivot/runClientPivot.js

@@ -0,0 +1,230 @@
+import { createLabelResolver } from "../columns/labels";
+import { getValue } from "../utils/getValue";
+import { compareValues } from "../utils/compare";
+import { aggregateValues } from "../client/aggregate";
+import { applyTransform } from "./transforms";
+/** 컬럼 타입별 사용 가능한 집계 — 백엔드 `COLUMN_TYPE_AGG_FUNCS` */
+export const AGG_FUNCS_BY_TYPE = {
+    number: ["SUM", "COUNT", "AVG", "MIN", "MAX", "COUNT_DISTINCT"],
+    date: ["COUNT", "MIN", "MAX", "COUNT_DISTINCT"],
+    datetime: ["COUNT", "MIN", "MAX", "COUNT_DISTINCT"],
+    text: ["COUNT", "COUNT_DISTINCT"],
+    boolean: ["COUNT", "COUNT_DISTINCT"],
+    enum: ["COUNT", "COUNT_DISTINCT"],
+    common_code: ["COUNT", "COUNT_DISTINCT"],
+    other: ["COUNT", "COUNT_DISTINCT"],
+};
+/** 피벗 집계 이름을 클라이언트 집계 키로 */
+const AGG_TO_FN = {
+    SUM: "sum", AVG: "avg", MIN: "min", MAX: "max",
+    COUNT_DISTINCT: "count_distinct", COUNT: "count",
+};
+export const PIVOT_SEPARATOR = "|";
+export function valueKeyOf(spec) {
+    return spec.alias ?? `${spec.source}_${spec.agg}`;
+}
+export function axisKeyOf(spec) {
+    if (spec.alias)
+        return spec.alias;
+    const transform = spec.transform ?? "none";
+    return transform === "none" ? spec.source : `${spec.source}_${transform}`;
+}
+function aggregate(rows, source, agg, registry) {
+    if (agg === "COUNT") {
+        // 백엔드 COUNT 는 NULL 이 아닌 값의 개수다
+        return rows.filter((row) => {
+            const value = getValue(row, source);
+            return value !== null && value !== undefined;
+        }).length;
+    }
+    const fn = AGG_TO_FN[agg];
+    return aggregateValues(rows.map((row) => getValue(row, source)), fn, {}, registry);
+}
+function passesHaving(rows, having, registry) {
+    for (const condition of having) {
+        const actual = Number(aggregate(rows, condition.source, condition.agg, registry));
+        if (Number.isNaN(actual))
+            return false;
+        const target = condition.value;
+        const ok = condition.operator === "eq" ? actual === target
+            : condition.operator === "ne" ? actual !== target
+                : condition.operator === "gt" ? actual > target
+                    : condition.operator === "gte" ? actual >= target
+                        : condition.operator === "lt" ? actual < target
+                            : actual <= target;
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+/** 한 축 레벨로 행을 나눈다. 순서는 값 오름차순, NULL 은 뒤 */
+function bucketize(rows, spec, resolveLabel) {
+    const map = new Map();
+    const transform = spec.transform ?? "none";
+    for (const row of rows) {
+        const { value, label } = applyTransform(getValue(row, spec.source), transform);
+        // 변환이 걸린 축은 변환 라벨("1월", "10만~20만")이 이미 의미를 갖는다.
+        // 변환 없는 축만 컬럼 선택지에서 이름을 찾는다.
+        const resolved = transform === "none" ? resolveLabel(spec.source, value) ?? label : label;
+        const key = String(value);
+        const bucket = map.get(key);
+        if (bucket)
+            bucket.rows.push(row);
+        else
+            map.set(key, { value, label: resolved, rows: [row] });
+    }
+    return [...map.values()].sort((a, b) => {
+        const aNull = a.value === null || a.value === undefined;
+        const bNull = b.value === null || b.value === undefined;
+        if (aNull || bNull)
+            return aNull && bNull ? 0 : aNull ? 1 : -1;
+        return compareValues(a.value, b.value);
+    });
+}
+/** 열 축 트리를 만들고 leaf 키 순서를 함께 낸다 */
+function buildColumnAxis(rows, specs, maxPivotValues, resolveLabel) {
+    const leafKeys = [];
+    const leafLabels = {};
+    let dropped = 0;
+    const build = (subset, depth, parentKey, parentLabels) => {
+        const spec = specs[depth];
+        const buckets = bucketize(subset, spec, resolveLabel);
+        const nodes = [];
+        for (const bucket of buckets) {
+            const key = parentKey ? `${parentKey}${PIVOT_SEPARATOR}${String(bucket.value)}` : String(bucket.value);
+            const labels = [...parentLabels, bucket.label];
+            const isLeaf = depth === specs.length - 1;
+            if (isLeaf) {
+                if (leafKeys.length >= maxPivotValues) {
+                    dropped += 1;
+                    continue;
+                }
+                leafKeys.push(key);
+                leafLabels[key] = labels;
+            }
+            nodes.push({
+                key,
+                label: bucket.label,
+                value: bucket.value,
+                source: spec.source,
+                depth,
+                children: isLeaf ? undefined : build(bucket.rows, depth + 1, key, labels),
+            });
+        }
+        // 하위가 전부 잘려나간 중간 노드는 헤더만 남으므로 제거한다
+        return nodes.filter((node) => node.children === undefined || node.children.length > 0);
+    };
+    const nodes = build(rows, 0, "", []);
+    return { nodes, leafKeys, leafLabels, dropped };
+}
+/**
+ * 클라이언트 피벗 — 백엔드 `PivotBuilder` 와 같은 계약으로 계산한다.
+ *
+ * 두 축은 **동등**하다. 행/열 전환은 `axes` 를 뒤집으면 되고 별도 경로가 없다.
+ */
+export function runClientPivot(rows, spec, options = {}) {
+    const [rowSpecs, colSpecs] = spec.axes;
+    if (rowSpecs.length === 0)
+        throw new Error("[koko-table] pivot: axes[0] 은 최소 1개 필요합니다");
+    if (colSpecs.length === 0)
+        throw new Error("[koko-table] pivot: axes[1] 은 최소 1개 필요합니다");
+    if (spec.values.length === 0)
+        throw new Error("[koko-table] pivot: values 는 최소 1개 필요합니다");
+    const maxPivotValues = spec.maxPivotValues ?? 50;
+    const having = spec.having ?? [];
+    const valueKeys = spec.values.map(valueKeyOf);
+    const resolveLabel = createLabelResolver(options.columns, options.labelOf);
+    const { nodes: columns, leafKeys, leafLabels, dropped } = buildColumnAxis(rows, colSpecs, maxPivotValues, resolveLabel);
+    /**
+     * 행 → 열 leaf 키를 **한 번만** 계산해 둔다.
+     *
+     * 이걸 안 해 두면 셀 하나를 만들 때마다 subset 전체를 다시 훑으며
+     * `applyTransform`(날짜 파싱 포함)을 부르게 된다 — 행 × leaf × 축 이라
+     * 실측에서 10,000 행 2x2 피벗이 67ms 였다. 미리 계산하면 행 × 축 로 떨어진다.
+     */
+    const leafKeyOf = new Map();
+    for (const row of rows) {
+        let key = "";
+        for (const colSpec of colSpecs) {
+            const { value } = applyTransform(getValue(row, colSpec.source), colSpec.transform ?? "none");
+            key = key ? `${key}${PIVOT_SEPARATOR}${String(value)}` : String(value);
+        }
+        leafKeyOf.set(row, key);
+    }
+    const shownLeafKeys = new Set(leafKeys);
+    /** 이 행 묶음에서 열 leaf 별 셀을 만든다 — subset 을 한 번만 훑는다 */
+    const cellsFor = (subset) => {
+        const byLeaf = new Map();
+        for (const row of subset) {
+            const key = leafKeyOf.get(row);
+            // 상한(maxPivotValues)으로 잘려나간 열은 셀도 만들지 않는다
+            if (!shownLeafKeys.has(key))
+                continue;
+            const bucket = byLeaf.get(key);
+            if (bucket)
+                bucket.push(row);
+            else
+                byLeaf.set(key, [row]);
+        }
+        const cells = {};
+        for (const [leafKey, matched] of byLeaf) {
+            const perValue = {};
+            spec.values.forEach((valueSpec, index) => {
+                perValue[valueKeys[index]] = aggregate(matched, valueSpec.source, valueSpec.agg, options.aggregations);
+            });
+            cells[leafKey] = perValue;
+        }
+        return cells;
+    };
+    const totalsFor = (subset) => {
+        const totals = {};
+        spec.values.forEach((valueSpec, index) => {
+            totals[valueKeys[index]] = aggregate(subset, valueSpec.source, valueSpec.agg, options.aggregations);
+        });
+        return totals;
+    };
+    const buildRows = (subset, depth, parentKey) => {
+        const rowSpec = rowSpecs[depth];
+        const buckets = bucketize(subset, rowSpec, resolveLabel);
+        const nodes = [];
+        for (const bucket of buckets) {
+            // HAVING 은 말단 행에만 적용한다 — 상위 그룹에 걸면 하위가 통째로 사라진다
+            const isLeaf = depth === rowSpecs.length - 1;
+            if (isLeaf && having.length > 0 && !passesHaving(bucket.rows, having, options.aggregations))
+                continue;
+            const key = parentKey ? `${parentKey}${PIVOT_SEPARATOR}${String(bucket.value)}` : String(bucket.value);
+            const children = isLeaf ? undefined : buildRows(bucket.rows, depth + 1, key);
+            if (children && children.length === 0)
+                continue; // 하위가 전부 걸러지면 상위도 뺀다
+            nodes.push({
+                key,
+                label: bucket.label,
+                value: bucket.value,
+                source: rowSpec.source,
+                depth,
+                cells: cellsFor(bucket.rows),
+                total: totalsFor(bucket.rows),
+                count: bucket.rows.length,
+                children,
+            });
+        }
+        return nodes;
+    };
+    // 열 합계 — 전체 원본 행을 열 leaf 로 나눠 행 total 과 같은 규칙으로 집계한다.
+    // (cellsFor(rows) 와 같은 계산이지만 뜻이 다르므로 이름을 따로 둔다)
+    const colTotals = cellsFor(rows);
+    return {
+        rows: buildRows(rows, 0, ""),
+        columns,
+        leafKeys,
+        leafLabels,
+        valueKeys,
+        grandTotal: totalsFor(rows),
+        colTotals,
+        droppedColumns: dropped,
+    };
+}
+/** 행/열 축 전환 — 두 축이 동등하므로 swap 이면 끝난다 */
+export function transposePivot(spec) {
+    return { ...spec, axes: [spec.axes[1], spec.axes[0]] };
+}

package/dist/core/src/pivot/transforms.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 피벗 축 변환 — 백엔드 `PivotBuilder/transforms` 와 값·라벨을 맞춘다.
+ * 변환된 **값**이 같은 그룹으로 묶이므로, 값이 어긋나면 축이 쪼개진다.
+ */
+export type ColumnTransform = "none" | "year" | "quarter" | "month" | "week" | "day_of_week" | "date" | "range_10k" | "range_100k" | "range_1m" | "range_10m" | "range_100m";
+export declare const TRANSFORM_LABELS: Record<ColumnTransform, string>;
+/** 컬럼 타입별 사용 가능한 변환 — 백엔드 `COLUMN_TYPE_TRANSFORMS` 와 같다 */
+export declare const TRANSFORMS_BY_TYPE: Record<string, ColumnTransform[]>;
+/** 한국식 금액 표기 — 백엔드 `_format_korean` 과 같은 규칙 */
+export declare function formatKoreanAmount(value: number): string;
+/** ISO 주차 (월요일 시작) */
+export declare function isoWeek(date: Date): number;
+export interface TransformedValue {
+    /** 그룹 키가 되는 값 */
+    value: unknown;
+    label: string;
+}
+/** 값 하나에 변환을 적용한다 */
+export declare function applyTransform(raw: unknown, transform: ColumnTransform): TransformedValue;

package/dist/core/src/pivot/transforms.js

@@ -0,0 +1,105 @@
+export const TRANSFORM_LABELS = {
+    none: "변환 없음",
+    month: "월", quarter: "분기", year: "연도", week: "주차",
+    day_of_week: "요일", date: "날짜",
+    range_10k: "1만 단위", range_100k: "10만 단위", range_1m: "100만 단위",
+    range_10m: "1000만 단위", range_100m: "1억 단위",
+};
+/** 컬럼 타입별 사용 가능한 변환 — 백엔드 `COLUMN_TYPE_TRANSFORMS` 와 같다 */
+export const TRANSFORMS_BY_TYPE = {
+    date: ["month", "quarter", "year", "week", "day_of_week", "date"],
+    datetime: ["month", "quarter", "year", "week", "day_of_week", "date"],
+    number: ["range_10k", "range_100k", "range_1m", "range_10m", "range_100m"],
+    text: [], boolean: [], enum: [], common_code: [], other: [],
+};
+const RANGE_UNITS = {
+    range_10k: 10_000,
+    range_100k: 100_000,
+    range_1m: 1_000_000,
+    range_10m: 10_000_000,
+    range_100m: 100_000_000,
+};
+const DAY_LABELS = ["일", "월", "화", "수", "목", "금", "토"];
+/** 한국식 금액 표기 — 백엔드 `_format_korean` 과 같은 규칙 */
+export function formatKoreanAmount(value) {
+    if (value === 0)
+        return "0";
+    const negative = value < 0;
+    const abs = Math.abs(value);
+    const eok = Math.floor(abs / 100_000_000);
+    const man = Math.floor((abs % 100_000_000) / 10_000);
+    const parts = [];
+    if (eok > 0)
+        parts.push(`${eok}억`);
+    if (man > 0)
+        parts.push(`${man}만`);
+    const body = parts.length > 0 ? parts.join("") : String(abs);
+    return negative ? `-${body}` : body;
+}
+/** ISO 주차 (월요일 시작) */
+export function isoWeek(date) {
+    const target = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    // 목요일 기준 — ISO 8601 은 그 주의 목요일이 속한 해를 그 주의 해로 본다
+    const dayOfWeek = (target.getDay() + 6) % 7;
+    target.setDate(target.getDate() - dayOfWeek + 3);
+    const firstThursday = new Date(target.getFullYear(), 0, 4);
+    const firstDayOfWeek = (firstThursday.getDay() + 6) % 7;
+    firstThursday.setDate(firstThursday.getDate() - firstDayOfWeek + 3);
+    return 1 + Math.round((target.getTime() - firstThursday.getTime()) / (7 * 24 * 3600 * 1000));
+}
+const pad = (n) => String(n).padStart(2, "0");
+function toDate(raw) {
+    if (raw instanceof Date)
+        return Number.isNaN(raw.getTime()) ? null : raw;
+    if (raw === null || raw === undefined || raw === "")
+        return null;
+    const date = new Date(String(raw));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** 값 하나에 변환을 적용한다 */
+export function applyTransform(raw, transform) {
+    if (transform === "none") {
+        return { value: raw, label: raw === null || raw === undefined ? "(비어 있음)" : String(raw) };
+    }
+    const unit = RANGE_UNITS[transform];
+    if (unit !== undefined) {
+        if (raw === null || raw === undefined || raw === "")
+            return { value: null, label: "(비어 있음)" };
+        const num = Number(raw);
+        if (Number.isNaN(num))
+            return { value: null, label: "(비어 있음)" };
+        const floor = Math.floor(num / unit) * unit;
+        return { value: floor, label: `${formatKoreanAmount(floor)}~${formatKoreanAmount(floor + unit)}` };
+    }
+    const date = toDate(raw);
+    if (date === null)
+        return { value: null, label: "(비어 있음)" };
+    switch (transform) {
+        case "year": {
+            const year = date.getFullYear();
+            return { value: year, label: `${year}년` };
+        }
+        case "quarter": {
+            const quarter = Math.floor(date.getMonth() / 3) + 1;
+            return { value: quarter, label: `Q${quarter}` };
+        }
+        case "month": {
+            const month = date.getMonth() + 1;
+            return { value: month, label: `${month}월` };
+        }
+        case "week": {
+            const week = isoWeek(date);
+            return { value: week, label: `${week}주차` };
+        }
+        case "day_of_week": {
+            const day = date.getDay();
+            return { value: day, label: DAY_LABELS[day] };
+        }
+        case "date": {
+            const ymd = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+            return { value: ymd, label: ymd };
+        }
+        default:
+            return { value: raw, label: String(raw) };
+    }
+}

package/dist/core/src/registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 확장점 공통 레지스트리 (설계 문서 4절).
+ *
+ * - 모든 확장점(셀 렌더러·집계·export 포맷터·메뉴·헤더·필터 kind)은 `{ id, … }` 항목의 레지스트리다.
+ * - `register()` 는 제자리 교체·추가(전역 기본 세트 조립용), `with()` 는 원본을 두고 새 레지스트리를 돌려준다.
+ * - core 에 두는 이유: 집계·export 포맷터 레지스트리는 React 를 모르는 core 가 소비한다.
+ *   mui 는 같은 것을 re-export 한다(`kokotable/mui` 의 `createRegistry` 와 동일 객체).
+ */
+export interface Registry<Def extends {
+    id: string;
+}> {
+    /** 같은 id 가 있으면 교체, 없으면 뒤에 추가 (mutable — 전역 기본 세트 조립용) */
+    register(def: Def): void;
+    /** id 로 제거 (mutable). 있었으면 true — 전역 등록을 되돌릴 때(테스트·HMR) */
+    unregister(id: string): boolean;
+    get(id: string): Def | undefined;
+    list(): Def[];
+    has(id: string): boolean;
+    /** 불변 파생 — add · remove · replace · order 를 적용한 새 레지스트리 */
+    with(overrides: RegistryPatch<Def>): Registry<Def>;
+}
+export interface RegistryPatch<Def extends {
+    id: string;
+}> {
+    /** 뒤에 추가 (같은 id 가 있으면 그 자리에서 교체) */
+    add?: Def[];
+    /** id 로 제거 */
+    remove?: string[];
+    /** 같은 id 항목을 제자리에서 교체 (없으면 뒤에 추가) */
+    replace?: Def[];
+    /** id 배열 순서로 정렬 — 없는 id 는 뒤에 원래 순서 */
+    order?: string[];
+}
+export declare function applyPatch<Def extends {
+    id: string;
+}>(items: Def[], patch: RegistryPatch<Def> | undefined): Def[];
+export declare function createRegistry<Def extends {
+    id: string;
+}>(base?: Def[]): Registry<Def>;
+export declare function isRegistry<Def extends {
+    id: string;
+}>(value: unknown): value is Registry<Def>;
+/** 배열 · 레지스트리 · undefined 를 모두 레지스트리로 (배열은 `base` 위에 add) */
+export declare function toRegistry<Def extends {
+    id: string;
+}>(value: Def[] | Registry<Def> | undefined, base?: Def[]): Registry<Def>;

package/dist/core/src/registry.js

@@ -0,0 +1,67 @@
+function upsert(items, def) {
+    const idx = items.findIndex((d) => d.id === def.id);
+    if (idx < 0)
+        return [...items, def];
+    const next = items.slice();
+    next[idx] = def;
+    return next;
+}
+export function applyPatch(items, patch) {
+    if (!patch)
+        return items;
+    let next = items;
+    for (const def of patch.replace ?? [])
+        next = upsert(next, def);
+    for (const def of patch.add ?? [])
+        next = upsert(next, def);
+    if (patch.remove?.length) {
+        const drop = new Set(patch.remove);
+        next = next.filter((d) => !drop.has(d.id));
+    }
+    if (patch.order?.length) {
+        const rank = new Map(patch.order.map((id, i) => [id, i]));
+        const ordered = next.filter((d) => rank.has(d.id)).sort((a, b) => rank.get(a.id) - rank.get(b.id));
+        const rest = next.filter((d) => !rank.has(d.id));
+        next = [...ordered, ...rest];
+    }
+    return next;
+}
+export function createRegistry(base = []) {
+    let items = base.slice();
+    const registry = {
+        register(def) {
+            items = upsert(items, def);
+        },
+        unregister(id) {
+            const next = items.filter((d) => d.id !== id);
+            const removed = next.length !== items.length;
+            items = next;
+            return removed;
+        },
+        get(id) {
+            return items.find((d) => d.id === id);
+        },
+        has(id) {
+            return items.some((d) => d.id === id);
+        },
+        list() {
+            return items.slice();
+        },
+        with(overrides) {
+            return createRegistry(applyPatch(items, overrides));
+        },
+    };
+    return registry;
+}
+export function isRegistry(value) {
+    return !!value && typeof value === "object"
+        && typeof value.list === "function" && typeof value.with === "function";
+}
+/** 배열 · 레지스트리 · undefined 를 모두 레지스트리로 (배열은 `base` 위에 add) */
+export function toRegistry(value, base = []) {
+    if (!value)
+        return createRegistry(base);
+    if (isRegistry(value))
+        return value;
+    return createRegistry(applyPatch(base, { add: value }));
+}