async-source v2.0.0

AsyncSource

AsyncSource is a stateful, reactive data source designed for managing asynchronous requests in modern JavaScript and TypeScript projects. It provides robust features for error handling, throttling, and caching, making it ideal for applications that require efficient data management.

Features

Stateful Management: Track the state of your requests, including (isLoading, isFetched, data).

Error Handling: Automatically manage errors with customizable handlers, ensuring a smooth user experience.

Debounce Control: Integrate built-in debouncing to manage rapid requests, preventing redundant calls and ensuring only the latest call is processed.

Cache Support: Cache responses locally with configurable storage options and expiration times, enhancing performance and reducing unnecessary network requests.

Automatic State Consistency: In cases of multiple calls, only the last call will be processed, maintaining data integrity and consistency.

Use Cases

• Connect AsyncSource to dynamic selects to efficiently handle user interactions and data fetching.
• Implement throttling and debouncing in applications that require real-time data updates without overwhelming the server.

Install

npm install --save async-source

Usage

// javascript
import AsyncSource from 'async-source';

const source = new AsyncSource(request);

async function loadItems() {
    await source.update(...requestParams);
    const response = source.data;
}

// typescript
import AsyncSource from 'async-source';

const source = new AsyncSource<RespnonsType>(request);

async function loadItems() {
    await source.update(...requestParams);
    const response = source.data;
}

Parameters

Properties(reactive getters)

Methods

Usage with vue3(composition api)

<template>
    <ul v-loading="isLoading">
        <li v-for="item in items" :key="item.id">
            {{ item.name }}
        </li>
    </ul>
</template>

<script>
import AsyncSource from 'async-source';
import { computed, reactive } from 'vue';

export default {
    name: 'MyComponent',
    setup() {
        function errorHandler(error) {
            console.error(error);
        }

        const source = reactive(new AsyncSource(request, errorHandler, 300));

        source.update();

        const items = computed(() => source.data || []);
        const isLoading = computed(() => source.isLoading);
        
        return {
            items,
            isLoading
        };
    }
}

</script>

Usage with vue2(option api)

<template>
    <ul v-loading="isLoading">
        <li v-for="item in items" :key="item.id">
            {{ item.name }}
        </li>
    </ul>
</template>

<script>
import AsyncSource from 'async-source';

export default {
    name: 'MyComponent',
    data() {
        return {
            source: new AsyncSource(request, this.errorHandler, 300)
        }
    },
    computed: {
        items() {
            return this.source.data || [];
        },
        isLoading() {
            return this.source.isLoading;
        }
    },
    created() {
        this.source.update();
    },
    methods: {
        errorHandler(error) {
            console.error(error);
        }
    }
}

</script>

Cache

Global cache configuration

To apply global settings, use setConfig:

import AsyncSource from 'async-source';

AsyncSource.setConfig({
    cacheStorage: localStorage,               // or any custom sync/async storage
    cacheTime: 12 * 60 * 60 * 1000,           // cache for 12 hours
    cachePrefix: 'MyAppAsyncSource'            // optional prefix for cache keys
});

Instance-Level Configuration

Specify custom settings for each AsyncSource instance by passing an options object as the third parameter. This object can include both caching and debounce settings.

new AsyncSource<T>(
    serviceMethod: (...args: any[]) => Promise<T>,
    errorHandler?: (error: any) => void,
    configOrDelay?: number | ConfigOptions
)

ConfigOptions Interface

If using a configuration object for configOrDelay, it can include:

interface ConfigOptions {
    debounceTime?: number;        // Delay before request execution (in milliseconds)
    requestCacheKey?: string;     // Request cache key (required for enable cache)
    cacheTime?: number;           // Cache expiration in milliseconds
    cacheStorage?: CacheStorage;  // Storage (e.g., localStorage, sessionStorage, indexDB)
    isUpdateCache?: boolean;      // Refetch cache every time when true.
}

Example

Sync storage

<template>
    <ul v-loading="isLoading">
        <li v-for="item in items" :key="item.id">
            {{ item.name }}
        </li>
    </ul>
</template>

<script>
import AsyncSource from 'async-source';
import { computed, reactive } from 'vue';

export default {
    name: 'MyComponent',
    setup() {
        function errorHandler(error) {
            console.error(error);
        }

        const source = reactive(
            new AsyncSource(request, errorHandler, {
                requestCacheKey: 'key',
                cacheStorage: sessionStorage,
                isUpdateCache: false,
                debounceTime: 100,
                cacheTime: 24 * 60 * 60 * 1000 // 24h
            })
        );
        source.update();

        const items = computed(() => source.data || []);
        const isLoading = computed(() => source.isLoading);
        
        return {
            items,
            isLoading
        };
    }
}

</script>

Async storage

<template>
    <ul v-loading="isLoading">
        <li v-for="item in items" :key="item.id">
            {{ item.name }}
        </li>
    </ul>
</template>

<script>
import AsyncSource from 'async-source';
import { computed, reactive } from 'vue';
import { get, set, del } from 'idb-keyval';

export default {
    name: 'MyComponent',
    setup() {
        function errorHandler(error) {
            console.error(error);
        }

        const storage = {
            getItem: (key: string) => get(key),
            setItem: (key: string, value: string) => set(key, value),
            removeItem: (key: string) => del(key)
        };

        const source = reactive(
            new AsyncSource(request, errorHandler, {
                requestCacheKey: 'key',
                cacheStorage: storage,
                isUpdateCache: false,
                debounceTime: 100,
                cacheTime: 24 * 60 * 60 * 1000 // 24h
            })
        );
        source.update();

        const items = computed(() => source.data || []);
        const isLoading = computed(() => source.isLoading);
        
        return {
            items,
            isLoading
        };
    }
}

</script>