Registry / http-networking / gitlab-api-async-iterator

gitlab-api-async-iterator

library1.3.1jsnpmunverified

This package provides an asynchronous iterator for the GitLab API, built on top of the popular `axios` HTTP client. It simplifies paginated API responses by allowing developers to iterate through all results using `for await...of` loops, abstracting away the complexities of managing `page` and `per_page` parameters. The current stable version is 1.3.1. While specific release cadence isn't stated, the package is actively maintained given its latest release. A key differentiator is its built-in retry mechanism for common API errors (429, 5xx series) and flexible configuration for GitLab API base URL and private tokens, which can be sourced from environment variables. It also offers a factory function to set up the underlying `axios` instance for direct API calls.

http-networking

npm install gitlab-api-async-iterator

package ↗homepage ↗

INSTALL

IMPORT

SIG · GITLAB-API-ASYNC-I

gitlab-api-async-iterator

http-networkingjavascriptv1.3.1

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.

setupGitLabAPI

✓ import { setupGitLabAPI } from 'gitlab-api-async-iterator';

✗ const { setupGitLabAPI } = require('gitlab-api-async-iterator');

While CJS `require` works, ESM `import` is preferred for modern JavaScript projects. This function is a factory for the API client.

GitLabPagedAPIIterator

✓ import { GitLabPagedAPIIterator } from 'gitlab-api-async-iterator';

✗ const GitLabPagedAPIIterator = require('gitlab-api-async-iterator').GitLabPagedAPIIterator;

This is the primary class for creating async iterators over paginated GitLab API endpoints. Instantiate with `new`.

GitLabAPI

✓ const GitLabAPI = setupGitLabAPI(axios, { privateToken: 'your_token' });

✗ import GitLabAPI from 'gitlab-api-async-iterator';

The `GitLabAPI` instance is *not* directly exported; it's the return value of `setupGitLabAPI`. Misunderstanding this can lead to import errors.

Demonstrates how to set up the GitLab API client and use the `GitLabPagedAPIIterator` to fetch and log projects, including handling authentication.

import axios from 'axios'; import { setupGitLabAPI, GitLabPagedAPIIterator } from 'gitlab-api-async-iterator'; // Ensure you have an environment variable like GITLAB_TOKEN set, or pass it directly. // For demonstration, we'll use a placeholder. const privateToken = process.env.GITLAB_TOKEN || 'YOUR_PRIVATE_GITLAB_TOKEN'; const GitLabAPI = setupGitLabAPI(axios, { baseURL: 'https://gitlab.com/api/v4/', privateToken: privateToken, maxRetries: 3 }); async function fetchProjects() { console.log('Fetching projects...'); try { // Create an iterator for the /projects endpoint const projectIterator = new GitLabPagedAPIIterator(GitLabAPI, '/projects', { // Optional: search for projects containing 'test' search: 'test', // Optional: limit to 2 pages max to avoid fetching too much data in example maxPages: 2 }); let projectCount = 0; for await (const project of projectIterator) { console.log(`- Project ID: ${project.id}, Name: ${project.name}`); projectCount++; if (projectCount >= 5) { console.log('Showing only first 5 projects for brevity.'); break; // Stop after a few projects for the example } } console.log(`Successfully fetched ${projectCount} projects.`); } catch (error) { console.error('Error fetching GitLab projects:', error.message); if (error.response && error.response.status === 401) { console.error('Check your GitLab private token.'); } } } fetchProjects();

Debug

Known issues

gotchaThe `setupGitLabAPI` function requires an `axios` instance as its first argument. Forgetting to pass it or passing a misconfigured `axios` instance will lead to runtime errors.

fix

Ensure `import axios from 'axios';` is present and pass the `axios` object correctly: `setupGitLabAPI(axios, options)`.

affects: >=1.0.0

gotchaGitLab API rate limits can be hit, even with the built-in retry mechanism. While the package retries 429 errors, sustained high request volume might still lead to delays or further errors if the retry limit is reached.

fix

Adjust the `maxRetries` option in `setupGitLabAPI` if necessary, or implement additional delays in your iteration logic. Monitor GitLab's `RateLimit-Remaining` and `RateLimit-Reset` headers if available.

affects: >=1.0.0

gotchaAuthentication requires a `privateToken` to be provided either directly in the `setupGitLabAPI` options or via `process.env.GITLAB_TOKEN` or `process.env.DANGER_GITLAB_API_TOKEN`. Failing to provide a valid token will result in 401 Unauthorized errors.

fix

Set the environment variable `GITLAB_TOKEN` (or `DANGER_GITLAB_API_TOKEN`) or explicitly pass `privateToken: 'your_token'` in the options object to `setupGitLabAPI`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'get')

The `GitLabAPI` instance was not correctly created via `setupGitLabAPI` or `axios` was not passed to it.

fix

Verify that `setupGitLabAPI(axios, options)` is called with a valid `axios` instance and its return value is assigned to `GitLabAPI`.

Error: Request failed with status code 401

The provided `privateToken` is missing, invalid, or lacks the necessary permissions for the requested endpoint.

fix

Check that `privateToken` is correctly set in `setupGitLabAPI` options or as an environment variable (`GITLAB_TOKEN` / `DANGER_GITLAB_API_TOKEN`) and ensure it has the required scopes on GitLab.

TypeError: projectIterator is not async iterable

Attempting to use `for await...of` on an object that is not an async iterator, possibly due to incorrect instantiation or an older Node.js version.

fix

Ensure `GitLabPagedAPIIterator` is correctly instantiated with `new` and check your Node.js version (async iterators typically require Node.js 10 or later). Also, verify the `GitLabAPI` instance passed to the iterator is valid.

Upgrade

Version history

1.3.1latest on npm

Audit

Dependencies

axiosrequiredUsed as the underlying HTTP client for making API requests to GitLab.

Agent activity

9 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/gitlab-api-async-iterator ↗

homepagehttps://gitlab.com/leipert-projects/npm-packages ↗