@osdk/react로 온톨로지 데이터 사용

@osdk/react는 온톨로지 SDK와 React 컴포넌트의 수명주기를 연결합니다. 타입이 있는 훅과 공유 캐시를 사용하므로 각 컴포넌트가 요청과 로딩 상태를 따로 구현할 필요를 줄일 수 있습니다. OSDK를 사용하는 React 앱에서는 이 라이브러리를 권장합니다.

제공 기능

• 객체, 객체 집합, 링크와 집계를 조회합니다.
• 액션을 검증하고 적용하며 낙관적 갱신을 지원합니다.
• 온톨로지 함수를 호출하고 의존 관계를 추적합니다.
• 정규화한 객체 캐시를 컴포넌트 사이에 공유합니다.
• 액션 뒤 영향을 받은 캐시의 객체를 동기화합니다.

설치와 클라이언트

아래 예제는 @osdk/api, @osdk/client, @osdk/react 2.83.0을 사용합니다. 기존 React 프로젝트의 의존성에 추가하며, 개발 도구가 이미 같은 호환 버전을 설치했다면 중복 설치하지 않습니다.

npm install @osdk/api@2.83.0 @osdk/client@2.83.0 @osdk/react@2.83.0

Developer Console의 SDK versions에서 필요한 객체와 액션을 포함한 npm SDK를 생성하고, 생성된 패키지를 프로젝트에 설치합니다. @my/osdk는 아래 예제에서 사용하는 패키지 이름이며 실제 생성한 SDK의 이름으로 바꿉니다.

OsdkProvider에는 인증과 온톨로지 설정을 마친 OSDK Client를 전달합니다. 앱 개발 환경이 생성한 클라이언트를 사용하거나 TypeScript 앱 설정에 따라 준비합니다. 클라이언트는 렌더마다 새로 만들지 않고 같은 인스턴스를 전달합니다. 모든 OSDK 훅을 사용하는 컴포넌트는 이 Provider 안에 있어야 합니다.

미완료 작업 조회

예제의 Todo에는 title, isComplete, createdAt 속성이 있어야 합니다. isComplete가 false인 작업을 생성 시각 내림차순으로 읽습니다. 파일은 JSX를 포함하므로 .tsx로 저장합니다.

import type { Client } from "@osdk/client";
import { OsdkProvider, useOsdkObjects } from "@osdk/react";
import { Todo } from "@my/osdk";

function TodoList() {
  const { data, error, isLoading } = useOsdkObjects(Todo, {
    orderBy: { createdAt: "desc" },
    where: { isComplete: false },
  });

  if (data == null && isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div role="alert">Error: {error.message}</div>;
  }
  if (data == null || data.length === 0) {
    return <div>No todos found</div>;
  }
  return (
    <div>
      {data.map(todo => <div key={todo.$primaryKey}>{todo.title}</div>)}
    </div>
  );
}

export function TodoApplication({ client }: { client: Client }) {
  return (
    <OsdkProvider client={client}>
      <TodoList />
    </OsdkProvider>
  );
}

이 예제는 첫 페이지를 표시합니다. useOsdkObjects의 autoFetchMore를 생략하면 첫 페이지만 읽으며, 추가 페이지는 반환된 fetchMore로 요청합니다. fetchMore가 undefined이면 더 읽을 페이지가 없습니다. data는 로드 전에는 undefined일 수 있고, 조회 실패는 error로 전달합니다.

설정 오류

2.83.0의 공개 OsdkProvider에서 필수인 props는 client와 children입니다. store를 요구하는 타입 오류가 나타나면 다른 버전이나 진입점의 Provider 선언을 참조하는지, @osdk/client와 @osdk/react의 버전이 호환되는지 확인합니다. Provider가 없거나 훅을 사용하는 컴포넌트보다 아래에 있으면 해당 컴포넌트는 클라이언트를 읽을 수 없습니다.

조건에 따라 조회를 중지하려면 훅 호출 자체를 조건문으로 감싸지 않고 enabled 옵션을 사용합니다. enabled: false에서는 새 서버 조회를 자동으로 실행하지 않지만 기존 캐시 데이터는 반환할 수 있습니다.

추가 설치 옵션과 훅 사용 예는 OSDK React 시작 안내에서 확인할 수 있습니다.