{"id":16038,"library":"gitlab-api-async-iterator","title":"GitLab API Async Iterator","description":"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.","status":"active","version":"1.3.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","gitlab","api","async","iterator"],"install":[{"cmd":"npm install gitlab-api-async-iterator","lang":"bash","label":"npm"},{"cmd":"yarn add gitlab-api-async-iterator","lang":"bash","label":"yarn"},{"cmd":"pnpm add gitlab-api-async-iterator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used as the underlying HTTP client for making API requests to GitLab.","package":"axios","optional":false}],"imports":[{"note":"While CJS `require` works, ESM `import` is preferred for modern JavaScript projects. This function is a factory for the API client.","wrong":"const { setupGitLabAPI } = require('gitlab-api-async-iterator');","symbol":"setupGitLabAPI","correct":"import { setupGitLabAPI } from 'gitlab-api-async-iterator';"},{"note":"This is the primary class for creating async iterators over paginated GitLab API endpoints. Instantiate with `new`.","wrong":"const GitLabPagedAPIIterator = require('gitlab-api-async-iterator').GitLabPagedAPIIterator;","symbol":"GitLabPagedAPIIterator","correct":"import { GitLabPagedAPIIterator } from 'gitlab-api-async-iterator';"},{"note":"The `GitLabAPI` instance is *not* directly exported; it's the return value of `setupGitLabAPI`. Misunderstanding this can lead to import errors.","wrong":"import GitLabAPI from 'gitlab-api-async-iterator';","symbol":"GitLabAPI","correct":"const GitLabAPI = setupGitLabAPI(axios, { privateToken: 'your_token' });"}],"quickstart":{"code":"import axios from 'axios';\nimport { setupGitLabAPI, GitLabPagedAPIIterator } from 'gitlab-api-async-iterator';\n\n// Ensure you have an environment variable like GITLAB_TOKEN set, or pass it directly.\n// For demonstration, we'll use a placeholder.\nconst privateToken = process.env.GITLAB_TOKEN || 'YOUR_PRIVATE_GITLAB_TOKEN';\n\nconst GitLabAPI = setupGitLabAPI(axios, {\n  baseURL: 'https://gitlab.com/api/v4/',\n  privateToken: privateToken,\n  maxRetries: 3\n});\n\nasync function fetchProjects() {\n  console.log('Fetching projects...');\n  try {\n    // Create an iterator for the /projects endpoint\n    const projectIterator = new GitLabPagedAPIIterator(GitLabAPI, '/projects', {\n      // Optional: search for projects containing 'test'\n      search: 'test',\n      // Optional: limit to 2 pages max to avoid fetching too much data in example\n      maxPages: 2\n    });\n\n    let projectCount = 0;\n    for await (const project of projectIterator) {\n      console.log(`- Project ID: ${project.id}, Name: ${project.name}`);\n      projectCount++;\n      if (projectCount >= 5) {\n        console.log('Showing only first 5 projects for brevity.');\n        break; // Stop after a few projects for the example\n      }\n    }\n    console.log(`Successfully fetched ${projectCount} projects.`);\n  } catch (error) {\n    console.error('Error fetching GitLab projects:', error.message);\n    if (error.response && error.response.status === 401) {\n      console.error('Check your GitLab private token.');\n    }\n  }\n}\n\nfetchProjects();\n","lang":"typescript","description":"Demonstrates how to set up the GitLab API client and use the `GitLabPagedAPIIterator` to fetch and log projects, including handling authentication."},"warnings":[{"fix":"Ensure `import axios from 'axios';` is present and pass the `axios` object correctly: `setupGitLabAPI(axios, options)`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set the environment variable `GITLAB_TOKEN` (or `DANGER_GITLAB_API_TOKEN`) or explicitly pass `privateToken: 'your_token'` in the options object to `setupGitLabAPI`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that `setupGitLabAPI(axios, options)` is called with a valid `axios` instance and its return value is assigned to `GitLabAPI`.","cause":"The `GitLabAPI` instance was not correctly created via `setupGitLabAPI` or `axios` was not passed to it.","error":"TypeError: Cannot read properties of undefined (reading 'get')"},{"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.","cause":"The provided `privateToken` is missing, invalid, or lacks the necessary permissions for the requested endpoint.","error":"Error: Request failed with status code 401"},{"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.","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.","error":"TypeError: projectIterator is not async iterable"}],"ecosystem":"npm"}