npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@edata-portal/icat-plus-api

v1.8.4

Published

This package provides a TypeScript client for the ICAT+ API.

Downloads

582

Readme

@edata-portal/icat-plus-api

This package provides a TypeScript client for the ICAT+ API.

Installation

pnpm install @edata-portal/icat-plus-api

You'll need to install @tanstack/react-query as a peer dependency if you haven't already:

pnpm install @tanstack/react-query

Usage

Configuration

Before using the API, you need to configure it with the base URL of the ICAT+ server and the authentication token.

import { IcatPlusAPIContext } from '@edata-portal/icat-plus-api';

function MyApp() {
  const queryClient = new QueryClient();

  return (
    <IcatPlusAPIContext.Provider
      value={{
        baseUrl: 'https://icatplus.esrf.fr/',
        sessionId: 'xxx', // OPTIONAL: You can omit this if you want to use routes without authentication
        sessionIdExpirationTime: 'xxx' // OPTIONAL: expiration time of the session ID - the data will be refetch when this value changes to ensure any data fetched after the expiration is refreshed
        onError: console.error, // OPTIONAL: A function that will be called with the message when an error occurs during a fetch
        onExpiredSessionId: logout, // OPTIONAL: A function that will be called when the session ID has expired and user needs to re-authenticate
      }}
    >
      // Your components
    </IcatPlusAPIContext.Provider>
  );
}

Endpoints

This package provides ICAT+ endpoints definitions through objects exported as constants. You can find them grouped by module under src/api/endpoints/modules directory. and import them like this:

import { DATASET_LIST_ENDPOINT } from '@edata-portal/icat-plus-api';

Then depending on the HTTP method associated with the endpoint, you can use one of the available hooks:

GET endpoints

useGetEndpoint

This hook allows to make your component dependant on a certain endpoint. It will fetch the data and return it. The component will be suspended while the data is being fetched.

const datasets = useGetEndpoint({
  endpoint: DATASET_LIST_ENDPOINT,
  params: {
    investigationIds: '123',
    nested: true,
  },
  // skipFetch: false, // add this param if you want to skip fetching the data under certain conditions
  // default: [] as Dataset[], // add this param if you want to provide a default value in case the data could not be fetched or the fetch was skipped
});

useAsyncFetchEndpoint

This hook allows to create a callback function that will create a promise to fetch the data.

const fetchDatasets = useAsyncFetchEndpoint(DATASET_LIST_ENDPOINT);

const onBtnClick = () => {
  fetchDatasets({
    investigationIds: '123',
    nested: true,
  }).then((datasets) => {
    console.log(datasets);
  });
};

useEndpointURL

This hook allows to get the full URL to the data, including authentication token if necessary. This is useful for images or downloading files.

const datasetsUrl = useEndpointURL(DATASET_LIST_ENDPOINT);

const url = datasetsUrl({
  investigationIds: '123',
  nested: true,
});

useMultiGetEndpoint

This hook allows to make multiple calls to the same endpoint with different params. It differs from multiple useGetEndpoint because the data will be fetch in parallel, while each useGetEndpoint will only be called after the previous one is done.

const datasetsUrl = useEndpointURL(DATASET_LIST_ENDPOINT);

const [datasets123, datasets456] = useMultiGetEndpoint({
  endpoint: DATASET_LIST_ENDPOINT,
  params: [
    {
      investigationIds: '123',
    },
    {
      investigationIds: '456',
    },
  ],
});

PUT, POST, DELETE & PATCH endpoints

useMutateEndpoint

This hook allows to create a callback function that will create a promise to send data to the server.

const createSession = useMutateEndpoint({
  endpoint: SESSION_CREATE_ENDPOINT,
});

createSession
  .mutateAsync({
    body: {
      plugin: 'db',
      username: 'user',
      password: 'password',
    },
  })
  .then((newUser) => {
    console.log(newUser);
  });

Suspend with ProgressSuspense

All components using useGetEndpoint and useMultiGetEndpoint will be suspended while the data is being fetched.

You can use React's Suspense component to display a fallback while the data is being fetched.

Additionally, this library provides a specialized ProgressSuspense component that will inform you of the progress while downloading large requests. This can be used as a replacement for the default Suspense component if you want to render a progress bar.

This component is only able to track the progress of the request if the server provides the Content-Length header in the response. If the server does not provide this header, the progress will be indeterminate.

Important to note, the progress initiates only after the server begins sending data, meaning it won't move until the server completes processing the request and starts sending the response. Due to this behavior, ProgressSuspense may not be suitable for requests with extended processing times and minimal data transfer, but it is well-suited for use cases involving long data transfer times, such as loading large files.

function renderProgress(v: number) {
  return <progress max={1} value={v}/>;
}

export function MyComponent() {
  return (
    <ProgressSuspense render={renderProgress}>
      <MySuspendedComponent>
    </ProgressSuspense>
  );
}