GitLab API Async Iterator

Common errors

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

  cause 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

  cause 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

  cause 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.

Warnings

• gotcha The `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)`.
• gotcha GitLab 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.
• gotcha Authentication 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`.

Install

• npm install gitlab-api-async-iterator npm
• yarn add gitlab-api-async-iterator yarn
• pnpm add gitlab-api-async-iterator pnpm

Imports

• setupGitLabAPI
  wrong:

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

  correct:

  import { setupGitLabAPI } from '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
  wrong:

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

  correct:

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

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

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

  correct:

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

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

Quickstart

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();