@volverjs/data NPM

@volverjs/data

repository http-client url-builder fetch

proudly powered by

Install

# pnpm
pnpm add @volverjs/data

# yarn
yarn add @volverjs/data

# npm
npm install @volverjs/data --save

Usage

This library exports four main classes: Hash, UrlBuilder, HttpClient and RepositoryHttp.

import { Hash, UrlBuilder, HttpClient, RepositoryHttp } from '@volverjs/data'

Hash

The Hash class provides some static functions to generate hashes.

import { Hash } from '@volverjs/data'
const hash = Hash.cyrb53('hello world')

UrlBuilder

The UrlBuilder class provides a way to build URLs with template parameters and query string.

import { UrlBuilder } from '@volverjs/data'

const urlBuilder = new UrlBuilder({
  encodeValuesOnly: false
})
const url = urlBuilder.build('https://api.com/:endpoint', {
  endpoint: 'users',
  _limit: 10,
  _page: 1
})
// url = 'https://api.com/users?_limit=10&_page=1'

Instead of URLSearchParams, the query parameters are automatically encoded using qs library. Please refer to the UrlBuilder docs for more informations.

HttpClient

The HttpClient class is a wrapper around ky, a client based on fetch API . It provides a simple interface to make HTTP requests and uses UrlBuilder to build URLs.

import { HttpClient } from '@volverjs/data'

const client = new HttpClient({
  prefixUrl: 'https://api.com'
})
const response = await client.get({
  template: ':endpoint/:action?/:id',
  params: {
    endpoint: 'users',
    id: 1,
    _limit: 10,
    _page: 1
  }
})
// fetch('https://api.com/users/1?_limit=10&_page=1', { method: 'GET' })

Please refer to the HttpClient docs for more informations.

RepositoryHttp

The RepositoryHttp class is an implementation of the Repository interface for http requests using HttpClient. It was designed with the repository pattern in mind to provide a simple way to make CRUD operations on a REST API.

import { HttpClient, RepositoryHttp } from '@volverjs/data'

class User {
  id: number
  name: string
  surname: string
  constructor(data: { id: number; name: string; surname: string }) {
    this.id = data.id
    this.name = data.name
    this.email = data.email
  }
  get fullName() {
    return `${this.name} ${this.surname}`
  }
}

const client = new HttpClient({
  prefixUrl: 'https://api.com'
})

const repository = new RepositoryHttp<User>(client, 'users/:group?/:id?', {
  class: User
})

const getAdminUsers: User[] = async () => {
  try {
    const { response } = repository.read({
      group: 'admin'
    })
    const { data } = await response
    return data
  } catch (error) {
    throw error
  }
}

Please refer to the RepositoryHttp docs for more informations.

Vue

You can use this library with Vue 3 with @volverjs/data/vue.

import { createApp } from 'vue'
import { createHttpClient } from '@volverjs/data/vue'

const httpClient = createHttpClient({
  prefixUrl: 'https://api.com'
})

const app = createApp(App)
app.use(httpClient, {
  global: true // default: false
})

With global option set to true, the HttpClient instance will be available in all components as $vvHttp.

Alternatively, you can use the useHttpClient function to inject the HttpClient instance in a specific component.

<script lang="ts" setup>
  import { useHttpClient } from '@volverjs/data/vue'

  const httpClient = useHttpClient()
  const response = await httpClient.get({
    template: 'users/:id',
    params: {
      id: 1
    }
  })
</script>

To use the RepositoryHttp class, you can use the useRepositoryHttp function.

<script lang="ts" setup>
  import { useRepositoryHttp } from '@volverjs/data/vue'

  class User {
    id: number
    name: string
    constructor(data: { id: number; name: string }) {
      this.id = data.id
      this.name = data.name
    }
  }

  const repository = useRepositoryHttp<User>('users/:id?', {
    class: User
  })
  const { response } = repository.read({
    id: 1
  })
  const { data } = await response
</script>