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

15 hits · last 30 days

node

Resources

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

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