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

Data Lens

지속해서 유지 관리하는 로컬 우선 CSV·JSON 웹 애플리케이션을 빌드, 테스트, 패키징하여 실행합니다.

Data Lens는 지속해서 유지 관리하는 다중 모듈 웹 애플리케이션 예제입니다. 사용자가 선택한 CSV나 JSON 파일을 엽니다. 브라우저 내부에서 행을 파싱하고 필터링합니다. 타입이 명시된 요약을 출력하고 텍스트 형태로 내보냅니다. 브라우저에 유지되는 영구 상태에는 화면 표시 설정만 저장합니다. 불러온 문서와 파싱한 행 데이터는 서버로 전송하지 않으며 저장하지도 않습니다.

본 가이드를 확인하기 전에 첫 애플리케이션을 먼저 완료하세요. 모듈, Result, 테스트, topaz.lock, --locked 개념에 익숙해야 합니다. 최종 브라우저 제품을 빌드하려면 wasm32-unknown-unknown 타겟이 설치된 Rust 툴체인도 필요합니다.

Web 애플리케이션인 이유

모델, 메시지, 상태 갱신 함수와 화면의 제어권을 토파즈가 소유할 때 web-app을 선택합니다. 기존 JavaScript 호스트가 UI나 Worker 프로토콜을 소유할 때만 순수 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 { 데이터형식, 데이터행, 정렬방식, 요약 }

export record 모델 {
  원문: string,
  질의: string,
  활성만: bool,
  형식: 데이터형식,
  정렬: 정렬방식,
  행들: Array<데이터행>,
  요약값: 요약,
  상태: string,
  오류: Option<string>,
}

파싱은 JSON $[0].category: missing field처럼 위치 정보가 명확한 Result를 반환합니다. 상태 갱신 함수는 해당 메시지를 오류 필드에 저장합니다. 화면은 이를 텍스트로 표시합니다. 원문 데이터를 innerHTML에 직접 처리해 넣지 않습니다.

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

TOPAZ
export function init() -> WebAppStep<모델, 메시지종류> {
  let 기준 = 모델 {
    원문: 예제자료,
    질의: "",
    활성만: false,
    형식: 데이터형식.쉼표구분,
    정렬: 정렬방식.이름순,
    행들: [],
    요약값: 빈요약(),
    상태: "Ready",
    오류: None,
  }
  WebAppStep {
    model: 모델적용(기준),
    commands: [상태불러오기("data-lens-session-load", "session", 메시지종류.로컬완료)],
  }
}

문서를 열 때는 사용자가 직접 문서를 선택합니다. 이후 제한된 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 파싱, 유니코드 레이블과 파일 이름 처리, 필터링, 두 정렬 방식, 텍스트 내보내기, 설정 저장·재로딩·삭제, 취소, 잘못된 문서 1건 및 잘못된 수정 후 복구 동작을 확인하세요. 소스 코드가 다시 올바른 상태가 될 때까지 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을 선택합니다.

관련 문서