@soie/data-manager NPM

@soie/data-manager

The @soie/data-manager library is designed to encapsulate Restful, GraphQL, localStorage, and sessionStorage, providing a simple way to handle asynchronous events.

@soie/data-manager

Installation

Using npm:

npm i @soie/data-manager

Using yarn:

yarn add @soie/data-manager

Using pnpm:

pnpm add @soie/data-manager

Configuration Options

createDataManager

requestConfig
- timeout
  - Specifies the timeout in milliseconds before a request times out. If the request takes longer than the timeout, it will be aborted.
  - type: number
  - default: undefined
- baseURL
  - Prepends the baseURL to the URL unless the URL is absolute.
  - type: string
  - default: ''
- headers
  - Allows you to add headers to every request. It can be a Headers object or an object literal with string values.
  - type: Header or object literal with String { "key": "value"}
  - default: undefined
storagePrefix
- Your localStorage or sessionStorage key prefix, default is 'data-manager'
  - localStorage: {storagePrefix}-ls-{your-key}
  - sessionStorage: {storagePrefix}-ss-{your-key}
- type: string
- default: 'data-manager'
transformer
- global transform key case for every request
  - transformRequestToSnakeCase: transform your request body or query string key into snake case
  - transformResponseToCamelCase: transform your response body's key into camel case
- default:
  - transformRequestToSnakeCase: false
  - transformResponseToCamelCase: false

Restful

query

endpoint

path
- type: string

params

type: any javascript object
default: undefined

 const { data } = await dataManager.query({ 
    path: 'https://some-api',
    params: {
      limit: 10,
      offset: 0,
    } 
})
// it will be generated to 'https://some-api?limit=10&offset=0'

arrayFormat

Serialize params arrays

bracket

 dataManager.query({ 
   path: 'https//example.com', 
   params: { foo: [1, 2, 3] },
   arrayFormat: 'bracket',
 })
 // https//example.com?foo[]=1&foo[]=2&foo[]=3

index

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'index',
})
// https//example.com?foo[0]=1&foo[1]=2&foo[2]=3

comma

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'comma',
})
// https//example.com?foo=1,2,3

separator

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'separator',
  arrayFormatSeparator: '|'
})
// https//example.com?foo=1|2|3

bracket-separator

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'bracket-separator',
  arrayFormatSeparator: '|'
})
// https//example.com?foo[]=1|2|3

colon-list-separator

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'colon-list-separator',
})
// https//example.com?foo:list=1&foo:list=2&foo:list=3

none

dataManager.query({ 
  path: 'https//example.com', 
  params: { foo: [1, 2, 3] },
  arrayFormat: 'colon-list-separator',
})
// https//example.com?foo=1&foo=2&foo=3

default: 'none'

arrayFormatSeparator
- The character used to separate array elements when using arrayFormat: 'separator' | 'bracket-separator'
- type: string
- default: ','
transformer
- only transform key case in this request
  - transformRequestToSnakeCase
    - transform your request body or query string key into snake case
    - type: boolean
    - default: Global transformer.transformRequestToSnakeCase
  - transformResponseToCamelCase
    - transform your response body's key into camel case
    - type: boolean
    - default: Global transformer.transformResponseToCamelCase
  - transformRequestExcludes
    - Exclude keys from being snake-cased.
    - type: Array<string | RegExp>
    - default: []
  - transformResponseExcludes
    - Exclude keys from being camel-cased.
    - type: Array<string | RegExp>
    - default: []
requestInit
- RequestInit MDN

response
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding to the status code
  - type: string
- header
  - The Headers object associated with the response.
  - type: Headers
  - Use headers.get('your header key') to get the header's value.
- data
  - The API response body in JSON format
errors
- If there is a request error, it will always return an error object
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding to the status code
  - type: string
- header
  - The Headers object associated with the response.
  - type: Headers
  - Use headers.get('your header key') to get the header's value
- message
  - If response.message can be parsed by JSON.parse, it will return the parsed object; otherwise, it returns a string

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager ({
  requestConfig: {
    timeout: 3000,
    baseURL: 'https://pokeapi.co/api/v2',
    headers: {
      Authorization: `Bearer ${your token}`,
    }
  },
  transformer: {
    transformRequestToSnakeCase: true,
    transformResponseToCamelCase: true,
  }
})

const getPokemonList = async () => {
  const { data } = await dataManager.query({ 
    path: '/pokemon',
    params: {
      limit: 10,
      offset: 0,
    } 
  })
  return data
}

Using with TypeScript

import { createDataManager } from '@soie/data-manager'

type PokemonList = {
  // ...
}

const dataManager = createDataManager ({
  requestConfig: {
    timeout: 3000,
    baseURL: 'https://pokeapi.co/api/v2',
    headers: {
      Authorization: `Bearer ${your token}`,
    }
  },
  transformer: {
    transformRequestToSnakeCase: true,
    transformResponseToCamelCase: true,
  }
})

const getPokemonList = async (): Promise<PokemonList> => {
  const { data } = await dataManager.query<PokemonList>({ 
    path: '/pokemon',
    params: {
      limit: 10,
      offset: 0,
    } 
  })
  return data
}

mutation

endpoint
- path
  - type: string
- params
  - Request body
  - type: Any JavaScript object
  - default: undefined
- method
  - Request method
  - type: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
- transformer
  - only transform key case in this request
    - transformRequestToSnakeCase
      - transform your request body or query string key into snake case
      - type: boolean
      - default: Global transformer.transformRequestToSnakeCase
    - transformResponseToCamelCase
      - transform your response body's key into camel case
      - type: boolean
      - default: Global transformer.transformResponseToCamelCase
    - transformRequestExcludes
      - Exclude keys from being snake-cased.
      - type: Array<string | RegExp>
      - default: []
    - transformResponseExcludes
      - Exclude keys from being camel-cased.
      - type: Array<string | RegExp>
      - default: []
- requestInit
  - RequestInit MDN
response
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding to the status code
  - type: string
- header
  - The Headers object associated with the response.
  - type: Headers
  - Use headers.get('your header key') to get the header's value.
- data
  - The API response body in JSON format
errors
- If there is a request error, it will always return an error object
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding to the status code
  - type: string
- header
  - The Headers object associated with the response.
  - type: Headers
  - Use headers.get('your header key') to get the header's value
- message
  - If response.message can be parsed by JSON.parse, it will return the parsed object; otherwise, it returns a string

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager({
  requestConfig: {
    timeout: 3000,
    baseURL: 'https://some-api/api',
    headers: {
      Authorization: `Bearer ${your token}`,
    }
  },
  transformer: {
    transformRequestToSnakeCase: true,
    transformResponseToCamelCase: true,
  }
})

const postPokemonName = async () => {
  await dataManager.mutation({ 
    path: '/pokemon',
    method: 'POST',
    params: {
      name: 'Hello'
    } 
  })
}

Using with typeScript

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager({
  requestConfig: {
    timeout: 3000,
    baseURL: 'https://some-api/api',
    headers: {
      Authorization: `Bearer ${your token}`,
    }
  },
  transformer: {
    transformRequestToSnakeCase: true,
    transformResponseToCamelCase: true,
  }
})

const postPokemonName = async () => {
  await dataManager.mutation<void>({ 
    path: '/pokemon',
    method: 'POST',
    params: {
      name: 'Hello'
    } 
  })
}

Storage

query

endpoint
- path
  - storage key, will be generated to
    - localStorage
      - ${storagePrefix}-ls-${ your key }
    - sessionStorage
      - ${storagePrefix}-ss-${ your key }
return
- data
  - string or JSON for storage

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager ({
  storagePrefix: 'hello'
})

// localStorage
const getLocalTheme = () => {
  const data = dataManager.ls.query('theme')
  return data
}

// sessionStorage
const getSessionTheme = () => {
  const data = dataManager.ss.query('theme')
  return data
}

Using with TypeScript

import { createDataManager } from '@soie/data-manager'

type Theme = {
  // ...
}

const dataManager = createDataManager ({
  storagePrefix: 'hello'
})

// localStorage
const getLocalTheme = () => {
  const data = dataManager.ls.query<Theme>('theme')
  return data
}

// sessionStorage
const getSessionTheme = () => {
  const data = dataManager.ss.query<Theme>('theme')
  return data
}

update

endpoint
- path
  - storage key, will be generated to
    - localStorage
      - ${storagePrefix}-ls-${ your key }
    - sessionStorage
      - ${storagePrefix}-ss-${ your key }
- params
  - any javascript object
return: void

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager({
  storagePrefix: 'hello'
})

// localStorage
const setLocalTheme = () => {
  dataManager.ls.update(
    'theme', 
    {
      primary: "#FF5533"
    },
  )
}

// sessionStorage
const setSessionTheme = () => {
  dataManager.ss.update(
    'theme', 
    {
      primary: "#FF5533"
    },
  )
}

delete

endpoint
- path
  - storage key, will be generated to
    - localStorage
      - ${storagePrefix}-ls-${ your key }
    - sessionStorage
      - ${storagePrefix}-ss-${ your key }
return: void

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager({
  storagePrefix: 'hello'
})

// localStorage
const deleteLocalTheme = () => {
  dataManager.ls.delete('theme')
}

// sessionStorage
const deleteSessionTheme = () => {
  dataManager.ss.delete('theme')
}

clear

clear all storage by prefix is
- localStorage
  - ${storagePrefix}-ls
- sessionStorage
  - ${storagePrefix}-ss
return: void

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager({
  storagePrefix: 'hello'
})

// localStorage
const clearAllLocalStorage = () => {
  dataManager.ls.clear()
}

// sessionStorage
const clearAllSessionStorage = () => {
  dataManager.ss.clear()
}

GraphQL

endpoint
- path
  - type: string
- params
  - query: graphql query schema
  - variables: graphql query variables optional
  - operationName: graphql operation name optional
- transformer
  - only transform key case in this request
    - transformResponseToCamelCase
      - transform your response body's key into camel case
      - type: boolean
      - default: Global transformer.transformResponseToCamelCase
    - transformResponseExcludes
      - Exclude keys from being camel-cased.
      - type: Array<string | RegExp>
      - default: []
- requestInit
  - RequestInit MDN
response
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding to the status code
  - type: string
- header
  - The Headers object associated with the response.
  - type: Headers
  - Use headers.get('your header key') to get the header's value
- data
  - The API response body in JSON format
errors
- If there is a request error, it will always return an error object
- status
  - The status code of the response
  - type: number
- statusText
  - The status message corresponding
- message
  - If response.message can be parsed by JSON.parse, it will return the parsed object; otherwise, it returns a string
- errors
  - Returns GraphQL errors or []
    - message
    - locations
    - path
    - extensions

Usage

import { createDataManager } from '@soie/data-manager'

const dataManager = createDataManager ({
  requestConfig: {
    timeout: 3000,
    baseURL: 'https://beta.pokeapi.co',
    headers: {
      Authorization: `Bearer ${your token}`,
    }
  }
})

// query
const getPokemonLocation = async () => {
  const { data } = await dataManager.gql({
    path: '/graphql/v1beta',
    params: { 
      query: `
        query locationAlola($region: String) {
          region: pokemon_v2_region(where: {name: {_eq: $region}}) {
            name
          }
        }
      `,
      variables: { 
        region: 'alola'
      },
      operationName: 'locationAlola'
    } 
  })
  return data
}

// mutation
const postPokemonLocation = async () => {
  await dataManager.gql({
    path: '/graphql',
    params: { 
      query: `
        mutation locationAlola($region: String) {
          region: pokemon_v2_region(where: {name: {_eq: $region}}) {
            name
          }
        }
      `,
      variables: { 
        region: 'alola'
      },
      operationName: 'locationAlola'
    } 
  })
}

Using with TypeScript

import { createDataManager } from '@soie/data-manager'

type PokemonLocation = {
  //...
}

const dataManager = createDataManager (
  requestConfig: {
    {
      timeout: 3000,
      baseURL: 'https://beta.pokeapi.co',
      headers: {
        Authorization: `Bearer ${your token}`,
      }
    }
  }
)

// query
const getPokemonLocation = async (): Promise<PokemonLocation> => {
  const { data } = await dataManager.gql<PokemonLocation>({
    path: '/graphql/v1beta',
    params: { 
      query: `
        query locationAlola($region: String) {
          region: pokemon_v2_region(where: {name: {_eq: $region}}) {
            name
          }
        }
      `,
      variables: { 
        region: 'alola'
      },
      operationName: 'locationAlola'
    } 
  })
  return data
}

// mutation
const postPokemonLocation = async () => {
  await dataManager.gql<void>({
    path: '/graphql',
    params: { 
      query: `
        mutation locationAlola($region: String) {
          region: pokemon_v2_region(where: {name: {_eq: $region}}) {
            name
          }
        }
      `,
      variables: { 
        region: 'alola'
      },
      operationName: 'locationAlola'
    } 
  })
}

fetch graphql http https ajax promise request localStorage sessionStorage

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago