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

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을 고릅니다.

관련 문서