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

snap-query

v0.7.8

Published

Snap Query is a minimalistic and type-safe library for creating custom query and mutation hooks in React. It leverages the power of nanostores, axios, and zod to provide a simple and efficient way to manage API requests and state in your application.

Downloads

102

Readme

Snap Query

Snap Query is a minimalistic and type-safe library for creating custom query and mutation hooks in React. It leverages the power of nanostores, axios, and zod to provide a simple and efficient way to manage API requests and state in your application.

Table of Contents

  1. Features
  2. Installation
  3. Usage
  4. Contributing
  5. License

Features

  • Atomic design: Designed for modular and maintainable code.
  • Easy to use: Simplifies data fetching with custom hooks.
  • Validation: Uses Zod for response data validation.
  • Lazy loading: Supports React Suspense for deferred loading.
  • Configurable logging: Control logging levels for debugging.

Installation

Install Snap Query via npm:

npm install snap-query

Usage

Overview

Snap Query provides a set of hooks for managing API requests and state in React applications. These hooks are built with type safety and simplicity in mind, ensuring that your data fetching and mutation logic is clean, maintainable, and reusable.

Hooks Provided:

  1. Query Hook: Used for fetching data from an API endpoint.
  2. Mutation Hook: Used for sending data to an API endpoint (e.g., creating or updating resources).
  3. Lazy Hook: Used for fetching data with React Suspense, allowing for deferred loading of components.

Creating a Query Hook

First, import the createQueryHook function from Snap Query:

import { createQueryHook } from "snap-query";

Define a URL and a DTO (Data Transfer Object) using Zod:

import { z } from "zod";

// Define the URL for the API endpoint with a parameter placeholder
const url = '/test/:myPathParam';

// Define the structure of the response data using Zod for validation
const dto = z.object({
    name: z.string(),
});

Create the query hook:

const [useQuery,  emitQuery] = createQueryHook(
  url,
  {
    defaultValidator: dto,   // (Optional) Validator for response data
    logLevel: 'debug',       // (Optional) default to 'none'
    // Additional axios request config options can be provided here
    // method: 'post',
    // baseURL: myBaseUrl,
  },
  axiosInstance  // (Optional) custom axios instance
);

Using the Query Hook

Use the query hook in your components:

import React, { useEffect } from "react";

export const TestComponent = () => {
    const params = React.useMemo(() => ({
        pathParams: { myPathParam: 'test' },
        skip: false,
        // Additional axios request config options
        // method: 'post',
        // baseURL: myBaseUrl,
    }), []);

    const queryResult = useQuery(params);

    if (queryResult.isError) {
        return (
            <div>error</div>
        );
    }

    return (
        <div>
            {queryResult.isLoading ? 'Loading...' : queryResult.data.name}
        </div>
    );
};

Creating a Mutation Hook

Import the createMutateHook function:

import { createMutateHook } from "snap-query";

Create the mutation hook:

const useMutate = createMutateHook(
  url,
  {
    defaultValidator: dto,   // (Optional) Validator for response data
    logLevel: 'debug',       // (Optional) default to 'none'
    // Additional axios request config options can be provided here
    // method: 'post',
    // baseURL: myBaseUrl,
  },
  axiosInstance  // (Optional) custom axios instance
);

Using the Mutation Hook

Use the mutation hook in your components:

import React from "react";

export const TestMutate = () => {
    const [{ cancel, mutate, reset }, queryResult] = useMutate({
        // Additional axios request config options can be provided here
        // method: 'post',
        // baseURL: myBaseUrl,
    });

    const onClick = () => {
        mutate({ pathParams: { myPathParam: 'test' } });
    };

    if (queryResult.isError) {
        return (
            <div>error</div>
        );
    }

    return (
        <>
            <button onClick={onClick}>Mutate</button>
            <div>
                {queryResult.isLoading ? 'Loading...' : queryResult.data.name}
            </div>
        </>
    );
};

Lazy Loading and Suspense

Snap Query supports React's Suspense for deferred loading of components.

Example:

Create a lazy hook:

import { createLazyHook } from "snap-query";

const useLazyUserQuery = createLazyHook(
  url,
  {
    defaultValidator: dto,   // (Optional) Validator for response data
    logLevel: 'debug',       // (Optional) default to 'none'
    // Additional axios request config options can be provided here
    // method: 'post',
    // baseURL: myBaseUrl,
  },
  axiosInstance  // (Optional) custom axios instance
);

Use it in your components:

import React, { Suspense, useMemo } from "react";
import { LazyResponse } from "snap-query";

const UserDataComponent = ({ resource }: { resource: LazyResponse<ResType> }) => {
    const res = resource.read();

    if (res?.error) {
        return <div>Error</div>;
    }

    return (
        <div>
            <h1>{res?.data?.id}</h1>
            <p>{res?.data?.title}</p>
        </div>
    );
};

const App = () => {
    const [count, setCount] = React.useState(1);

    const queryParams = useMemo(() => ({
        pathParams: { id: count },
        validator: ResDto,
        // Additional axios request config options can be provided here
        // method: 'post',
        // baseURL: myBaseUrl,
    }), [count]);

    const lazyResult = useLazyUserQuery(queryParams);

    return (
        <Suspense fallback={<div>Loading...</div>}>
            <UserDataComponent resource={lazyResult} />
        </Suspense>
    );
};

Contributing

Pull requests are welcome. Please ensure you update tests as appropriate.

License

This project is licensed under the MIT License.