Registry / http-networking / purest

purest

JSON →
library0.0.2jsnpmunverified

Purest is a flexible JavaScript library for constructing expressive REST API clients, abstracting away the low-level HTTP request details. It enables developers to define detailed API configurations, including base URLs, paths, headers, and versioning, for various service providers. The library then facilitates interaction through a fluent, chainable API that supports custom query parameters, authentication, and HTTP methods, with options for preconfigured defaults and method aliases. Currently in stable version 4.0.3, Purest is actively maintained, supporting Node.js environments (>=12.0.0) and ships with TypeScript types for improved developer experience. It relies on the `request-compose` library for its underlying HTTP capabilities. Purest differentiates itself by providing a highly configurable and declarative approach to API consumption, allowing for complex API structures to be represented and interacted with in an abstract yet powerful manner, making it suitable for managing interactions with multiple, diverse REST APIs within a single application.

npm install purest
INSTALL
IMPORT
SIG · PUREST
P
purest
http-networkingjavascriptv0.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

purest
✓ import purest from 'purest'
✗ import { purest } from 'purest'
The `purest` factory function is the default export. Use `require('purest')` for CommonJS.
PurestClient
✓ import type { PurestClient } from 'purest'
Import the `PurestClient` type for improved type-checking and IntelliSense when working with instantiated Purest clients.

This example demonstrates how to configure a Purest client for Google's YouTube API, apply an authentication token, query for channels by username, and execute the request.

import purest from 'purest'; const config = { "google": { "default": { "origin": "https://www.googleapis.com", "path": "{path}", "headers": { "authorization": "Bearer {auth}" } }, "youtube": { "origin": "https://www.googleapis.com", "path": "youtube/{version}/{path}", "version": "v3", "headers": { "authorization": "Bearer {auth}" } } } }; async function getYouTubeChannels(username: string, token: string) { const google = purest({ provider: 'google', config }); try { const { res, body } = await google('youtube') .get('channels') .qs({ forUsername: username }) .auth(token) .request(); console.log('Status:', res.statusCode); console.log('Body:', JSON.stringify(body, null, 2)); return body; } catch (error) { console.error('Error fetching YouTube channels:', error); throw error; } } // Example usage: replace with your actual Google API token and desired username const GOOGLE_AUTH_TOKEN = process.env.GOOGLE_AUTH_TOKEN ?? 'YOUR_GOOGLE_AUTH_TOKEN'; const TARGET_USERNAME = 'GitHub'; if (GOOGLE_AUTH_TOKEN === 'YOUR_GOOGLE_AUTH_TOKEN') { console.warn("Please set GOOGLE_AUTH_TOKEN environment variable or replace 'YOUR_GOOGLE_AUTH_TOKEN' with an actual token to run this example."); } else { getYouTubeChannels(TARGET_USERNAME, GOOGLE_AUTH_TOKEN) .then(() => console.log(`Attempted to fetch YouTube channels for ${TARGET_USERNAME}.`)) .catch(() => console.error('Failed to execute YouTube channel fetch example.')); }
Debug
Known issues
breakingMajor version upgrades (e.g., v2 to v3, or v3 to v4) introduce breaking changes to the API configuration format, method signatures, or internal behavior. Direct upgrades between major versions without code adjustments are generally not supported.
fix
Always consult the official migration guides provided in the GitHub repository or npm documentation when upgrading Purest across major versions to understand necessary configuration and code changes.
affects: >=2.0.0
gotchaForgetting to call `.request()` at the end of a method chain will not dispatch the HTTP request. The chain merely builds the request definition until `.request()` is explicitly called.
fix
Ensure all Purest method chains are terminated with a call to `.request()` (e.g., `purestClient.get('path').auth(token).request()`) to execute the API call.
affects: >=1.0.0
gotchaThe configuration object for API providers can be complex, especially with dynamic tokens like `{path}`, `{version}`, and `{auth}`. Incorrectly defined origins, paths, or headers will lead to malformed URLs or failed authentication.
fix
Carefully verify the structure and token placement within your `config` object for each provider. Ensure that `auth()` calls match the `{auth}` token in your headers configuration, and `{path}` and `{version}` tokens are correctly used in URL paths.
affects: >=1.0.0
gotchaWhen using TypeScript or modern JavaScript with ESM, attempting to import `purest` as a named export (`import { purest } from 'purest'`) will result in a runtime error because `purest` is a default export.
fix
Always use the default import syntax: `import purest from 'purest';` for ESM, or `const purest = require('purest');` for CommonJS.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: purest is not a function
This typically occurs when using an incorrect import statement for Purest, treating its default export as a named export.
fix
Change your import statement from `import { purest } from 'purest';` to `import purest from 'purest';`.
TypeError: Cannot read properties of undefined (reading 'request')
This error indicates that the object you are trying to call `.request()` on is undefined. This often happens if the `purest()` call itself failed to return a valid client instance, possibly due to missing or invalid provider configuration.
fix
Verify that your `purest({provider: 'your-provider', config})` call is correctly configured and successfully returns a client object before attempting to chain methods or call `.request()`.
Error: Missing provider configuration for 'your-provider'
The `config` object passed to `purest` either does not contain a definition for the specified `provider` name, or the configuration for that provider is malformed or empty.
fix
Ensure your `config` object includes a correctly structured entry for the provider name you are trying to initialize (e.g., `config = { 'google': { ... } }`).
Upgrade
Version history
0.0.2latest on npm
Audit
Dependencies
request-composerequiredPurest is built on top of this powerful HTTP client for making requests.
Agent activity
4 hits · last 30 days
node
4
Resources
purest — npm install purest · libregistry