토파즈문서
애플리케이션 만들기

Data Lens

유지 관리 대상인 로컬 우선 CSV·JSON Web 애플리케이션을 빌드하고 테스트하고 패키징해 실행합니다.

Data Lens는 유지 관리되는 다중 모듈 Web 애플리케이션 예제입니다. 사용자가 고른 CSV 또는 JSON을 열고, 브라우저 안에서 행을 파싱하고 필터링하며, 타입이 있는 요약을 보여 주고 텍스트로 내보냅니다. 영구 브라우저 상태에는 보기 설정만 저장하며 가져온 문서와 파싱한 행을 서버로 보내거나 저장하지 않습니다.

이 가이드보다 먼저 첫 애플리케이션을 완료하세요. 모듈, Result, 테스트, topaz.lock, --locked에 익숙해야 합니다. 최종 브라우저 제품을 빌드하려면 wasm32-unknown-unknown 대상이 설치된 Rust 도구 모음도 필요합니다.

Web 애플리케이션인 이유

모델, 메시지, 상태 갱신 함수와 화면을 토파즈가 소유할 때 web-app을 선택합니다. 기존 JavaScript 호스트가 UI나 Worker 프로토콜을 소유할 때만 raw web 또는 web-worker를 선택하세요. 플레이그라운드는 짧은 소스 실험을 위한 곳이지 Data Lens 배포 수단이 아닙니다.

유지 관리 대상 소스는 진입 파일 하나에 몰지 않고 책임별로 나뉩니다.

출력
data-lens/
  topaz.toml
  topaz.lock
  src/main.tpz
  src/model.tpz
  src/session.tpz
  src/view.tpz
  tests/application.tpz
  tests/exporting.tpz
  tests/parsing.tpz
  tests/transform.tpz
  styles/app.css
  registry/lens_labels/1.0.0/...
  vendor/lens_labels/1.0.0/...

data-lens-core/
  topaz.toml
  src/lib.tpz

data-lens-core는 CSV·JSON 파싱, 필터링, 정렬, 요약과 내보내기를 담당합니다. Web 패키지는 브라우저 메시지, 로컬 상태 인코딩과 화면을 담당합니다. lens_labels는 잠금 파일로 고정해 vendor에 복사한 레지스트리 의존성입니다.

UI보다 먼저 데이터 모델링하기

애플리케이션 모델은 원문, 조작 값, 타입이 있는 행, 요약과 표시할 오류를 분리합니다.

TOPAZ
import data_lens_core { DataFormat, DataRow, SortMode, Summary }

export record Model {
  source: string,
  query: string,
  activeOnly: bool,
  format: DataFormat,
  sortMode: SortMode,
  rows: Array<DataRow>,
  summary: Summary,
  status: string,
  error: Option<string>,
}

파싱은 JSON $[0].category: missing field처럼 위치가 안정적인 Result를 돌려줍니다. 상태 갱신 함수는 메시지를 error에 저장하고 화면은 이를 텍스트로 표시합니다. 원문을 innerHTML로 삽입하지 않습니다.

생명주기는 메모리의 예제 데이터로 시작하고 저장된 보기 설정만 요청합니다.

TOPAZ
export function init() -> WebAppStep<Model, Msg> {
  let base = Model {
    source: CSV_SAMPLE,
    query: "",
    activeOnly: false,
    format: DataFormat.Csv,
    sortMode: SortMode.ByName,
    rows: [],
    summary: emptySummary(),
    status: "Ready",
    error: None,
  }
  WebAppStep {
    model: applyModel(base),
    commands: [loadState("data-lens-session-load", "session", Msg.LocalCompleted)],
  }
}

문서 열기는 사용자가 명시적으로 선택한 뒤 제한된 UTF-8 텍스트만 전달합니다. 세션 저장은 검색어, 활성 행 필터와 정렬 방식만 기록합니다. 취소, 잘못된 UTF-8, 저장소 사용 불가, 용량 초과와 손상된 저장 상태는 모두 애플리케이션이 처리할 수 있는 타입이 있는 결과로 남습니다.

가장 짧은 유지 관리 작업 경로

애플리케이션을 작성할 때 레지스트리 입력과 이웃한 코어 패키지를 함께 만듭니다. 그런 다음 한 번 벤더링합니다. vendor는 레지스트리 의존성을 검증해 복사하고 잠금 파일도 기록합니다. 아직 벤더링하지 않은 레지스트리 의존성에 lock을 먼저 실행하지 마세요.

BASH
topaz vendor --root data-lens --from data-lens/registry
topaz fmt --check --root data-lens
topaz check --root data-lens --locked
topaz test data-lens/tests/parsing.tpz --root data-lens --locked
topaz test data-lens/tests/transform.tpz --root data-lens --locked
topaz test data-lens/tests/application.tpz --root data-lens --locked
topaz test data-lens/tests/exporting.tpz --root data-lens --locked
topaz dev --root data-lens --port 8000
topaz build --root data-lens --locked --release --out-dir data-lens-product

topaz run은 main이 있는 명령형 진입점의 직접 실행 경로입니다. Data Lens는 Web 생명주기를 사용하므로 눈으로 확인하는 개발 명령은 topaz dev입니다.

브라우저에서 CSV와 JSON, 유니코드 레이블과 파일 이름, 필터링, 두 정렬 방식, 텍스트 내보내기, 설정 저장·재로딩·삭제, 취소, 잘못된 문서 하나와 잘못된 수정 뒤 복구를 확인하세요. 소스가 다시 올바르게 될 때까지 topaz dev는 마지막 정상 제품을 계속 제공합니다.

제품과 토파즈 패키지 소스 없는 실행

관리형 제품에는 다음 파일이 들어갑니다.

출력
data-lens-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── index.html
├── styles
│   └── app.css
├── topaz-app.js
├── topaz-artifact.json
├── topaz-web-capabilities.json
├── topaz-web.d.ts
├── topaz-web.js
└── topaz-web.wasm

디렉터리 전체를 새로운 정적 루트로 복사해 HTTP로 제공하세요. 패키지 소스, 토파즈 CLI, 레지스트리, npm 런타임, CDN이나 데이터 서비스는 필요하지 않습니다. file://에서 ES 모듈이나 WASM을 불러오지 못하면 로컬 정적 HTTP 서버를 사용하세요. 관리 파일이 달라졌거나 다른 대상이 출력 디렉터리를 소유해 빌드가 거부되면 기존 디렉터리를 보존하고 새 빈 --out-dir을 선택합니다.

관련 문서