arxiv-api-wrapper 1.0.1 → 1.1.1

package/.github/workflows/static.yml

@@ -0,0 +1,66 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm ci
+      - name: Generate documentation
+        run: npm run docs:generate
+      - name: Configure git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+      - name: Commit generated docs
+        run: |
+          git add docs/
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "docs: regenerate documentation [skip ci]"
+            git push
+          fi
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload docs path
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/README.md

@@ -1,209 +1,250 @@
-# arxiv-api-wrapper
-
-A TypeScript package that provides a convenient wrapper around the arXiv API, enabling easy querying and parsing of arXiv papers.
-
-## Installation
-
-```bash
-npm install arxiv-api-wrapper
-```
-
-## Quick Start
-
-```typescript
-import { getArxivEntries } from 'arxiv-api-wrapper';
-
-const result = await getArxivEntries({
-  search: {
-    title: ['quantum computing'],
-    author: ['John Doe'],
-  },
-  maxResults: 10,
-  sortBy: 'submittedDate',
-  sortOrder: 'descending',
-});
-
-console.log(`Found ${result.feed.totalResults} papers`);
-result.entries.forEach(entry => {
-  console.log(`${entry.arxivId}: ${entry.title}`);
-});
-```
-
-## Features
-
-- **Type-safe**: Full TypeScript support with comprehensive type definitions
-- **Flexible Search**: Support for complex queries with multiple filters, OR groups, and negation
-- **Rate Limiting**: Built-in token bucket rate limiter to respect arXiv API guidelines
-- **Retry Logic**: Automatic retries with exponential backoff for transient failures
-- **Pagination**: Support for paginated results with configurable page size
-- **Sorting**: Multiple sort options (relevance, submission date, last updated)
-
-## API Reference
-
-For complete API documentation with detailed type information and examples, see the [generated API documentation](./docs/index.html) (generate with `npm run docs:generate`).
-
-### `getArxivEntries(options: ArxivQueryOptions): Promise<ArxivQueryResult>`
-
-Main function to query the arXiv API.
-
-**Options:**
-- `idList?: string[]` - List of arXiv IDs to fetch (e.g., `['2101.01234', '2101.05678']`)
-- `search?: ArxivSearchFilters` - Search filters (ignored if `idList` is provided)
-- `start?: number` - Pagination offset (0-based)
-- `maxResults?: number` - Maximum number of results (≤ 300)
-- `sortBy?: 'relevance' | 'lastUpdatedDate' | 'submittedDate'` - Sort field
-- `sortOrder?: 'ascending' | 'descending'` - Sort direction
-- `timeoutMs?: number` - Request timeout in milliseconds (default: 10000)
-- `retries?: number` - Number of retry attempts (default: 3)
-- `rateLimit?: { tokensPerInterval: number, intervalMs: number }` - Rate limit configuration
-- `userAgent?: string` - Custom User-Agent header
-
-**Search Filters:**
-- `title?: string[]` - Search in titles
-- `author?: string[]` - Search by author names
-- `abstract?: string[]` - Search in abstracts
-- `category?: string[]` - Filter by arXiv categories
-- `submittedDateRange?: { from: string, to: string }` - Date range filter (YYYYMMDDTTTT format)
-- `or?: ArxivSearchFilters[]` - OR group of filters
-- `andNot?: ArxivSearchFilters` - Negated filter (ANDNOT)
-
-**Returns:**
-```typescript
-{
-  feed: {
-    id: string;
-    updated: string;
-    title: string;
-    link: string;
-    totalResults: number;
-    startIndex: number;
-    itemsPerPage: number;
-  };
-  entries: Array<{
-    id: string;
-    arxivId: string;
-    title: string;
-    summary: string;
-    published: string;
-    updated: string;
-    authors: Array<{ name: string; affiliation?: string }>;
-    categories: string[];
-    primaryCategory?: string;
-    links: Array<{ href: string; rel?: string; type?: string; title?: string }>;
-    doi?: string;
-    journalRef?: string;
-    comment?: string;
-  }>;
-}
-```
-
-## Examples
-
-### Search by title and author
-
-```typescript
-const result = await getArxivEntries({
-  search: {
-    title: ['machine learning'],
-    author: ['Geoffrey Hinton'],
-  },
-  maxResults: 5,
-});
-```
-
-### Fetch specific papers by ID
-
-```typescript
-const result = await getArxivEntries({
-  idList: ['2101.01234', '2101.05678'],
-});
-```
-
-### Complex search with OR and date range
-
-```typescript
-const result = await getArxivEntries({
-  search: {
-    or: [
-      { title: ['quantum'] },
-      { abstract: ['quantum'] },
-    ],
-    submittedDateRange: {
-      from: '202301010600',
-      to: '202401010600',
-    },
-  },
-  sortBy: 'submittedDate',
-  sortOrder: 'descending',
-});
-```
-
-### With rate limiting
-
-```typescript
-const result = await getArxivEntries({
-  search: { title: ['neural networks'] },
-  rateLimit: {
-    tokensPerInterval: 1,
-    intervalMs: 3000, // 1 request per 3 seconds
-  },
-});
-```
-
-## Documentation
-
-### Generating API Documentation
-
-To generate browsable API documentation from the source code:
-
-```bash
-npm run docs:generate
-```
-
-This will create HTML documentation in the `docs/` directory. You can then view it locally:
-
-```bash
-npm run docs:serve
-```
-
-The generated documentation includes:
-- Complete API reference for all exported functions and types
-- Detailed parameter descriptions and examples
-- Type information and relationships
-- Search functionality
-
-### IDE IntelliSense
-
-All exported functions and types include JSDoc comments for enhanced IDE IntelliSense support. Hover over any exported symbol in your IDE to see inline documentation.
-
-## TypeScript Types
-
-All types are exported from the package:
-
-```typescript
-import type {
-  ArxivQueryOptions,
-  ArxivQueryResult,
-  ArxivSearchFilters,
-  ArxivEntry,
-  ArxivFeedMeta,
-  ArxivAuthor,
-  ArxivLink,
-  ArxivSortBy,
-  ArxivSortOrder,
-  ArxivRateLimitConfig,
-  ArxivDateRange,
-} from 'arxiv-api-wrapper';
-```
-
-## License
-
-ISC
-
-## Author
-
-Vilhelm Agdur
-
-## Repository
-
-https://github.com/vagdur/arxiv-api-wrapper
+# arxiv-api-wrapper
+
+A TypeScript package that provides a convenient wrapper around the arXiv API, enabling easy querying and parsing of arXiv papers.
+
+## Installation
+
+```bash
+npm install arxiv-api-wrapper
+```
+
+## Quick Start
+
+```typescript
+import { getArxivEntries, getArxivEntriesById } from 'arxiv-api-wrapper';
+
+// Search for papers
+const result = await getArxivEntries({
+  search: {
+    title: ['quantum computing'],
+    author: ['John Doe'],
+  },
+  maxResults: 10,
+  sortBy: 'submittedDate',
+  sortOrder: 'descending',
+});
+
+console.log(`Found ${result.feed.totalResults} papers`);
+result.entries.forEach(entry => {
+  console.log(`${entry.arxivId}: ${entry.title}`);
+});
+
+// Or fetch specific papers by ID
+const papers = await getArxivEntriesById(['2101.01234', '2101.05678']);
+```
+
+## Features
+
+- **Type-safe**: Full TypeScript support with comprehensive type definitions
+- **Flexible Search**: Support for complex queries with multiple filters, OR groups, and negation
+- **Rate Limiting**: Built-in token bucket rate limiter to respect arXiv API guidelines
+- **Retry Logic**: Automatic retries with exponential backoff for transient failures
+- **Pagination**: Support for paginated results with configurable page size
+- **Sorting**: Multiple sort options (relevance, submission date, last updated)
+
+## API Reference
+
+For complete API documentation with detailed type information and examples, see the [generated API documentation](https://vagdur.github.io/arxiv-api-wrapper/).
+
+### `getArxivEntriesById(ids: string[], options?): Promise<ArxivQueryResult>`
+
+Simpler function to fetch arXiv papers by their IDs using the id_list API mode.
+
+**Parameters:**
+- `ids: string[]` - Array of arXiv paper IDs (e.g., `['2101.01234', '2101.05678']`)
+- `options?: object` - Optional request configuration
+  - `rateLimit?: { tokensPerInterval: number, intervalMs: number }` - Rate limit configuration
+  - `retries?: number` - Number of retry attempts (default: 3)
+  - `timeoutMs?: number` - Request timeout in milliseconds (default: 10000)
+  - `userAgent?: string` - Custom User-Agent header
+
+**Returns:** Same as `getArxivEntries` - see return type below.
+
+### `getArxivEntries(options: ArxivQueryOptions): Promise<ArxivQueryResult>`
+
+Main function to query the arXiv API with search filters or ID lists.
+
+**Options:**
+- `idList?: string[]` - List of arXiv IDs to fetch (e.g., `['2101.01234', '2101.05678']`)
+- `search?: ArxivSearchFilters` - Search filters (when used with `idList`, filters the entries from `idList` to only return those matching the search query)
+- `start?: number` - Pagination offset (0-based)
+- `maxResults?: number` - Maximum number of results (≤ 300)
+- `sortBy?: 'relevance' | 'lastUpdatedDate' | 'submittedDate'` - Sort field
+- `sortOrder?: 'ascending' | 'descending'` - Sort direction
+- `timeoutMs?: number` - Request timeout in milliseconds (default: 10000)
+- `retries?: number` - Number of retry attempts (default: 3)
+- `rateLimit?: { tokensPerInterval: number, intervalMs: number }` - Rate limit configuration
+- `userAgent?: string` - Custom User-Agent header
+
+**Search Filters:**
+- `title?: string[]` - Search in titles
+- `author?: string[]` - Search by author names
+- `abstract?: string[]` - Search in abstracts
+- `category?: string[]` - Filter by arXiv categories
+- `submittedDateRange?: { from: string, to: string }` - Date range filter (YYYYMMDDTTTT format)
+- `or?: ArxivSearchFilters[]` - OR group of filters
+- `andNot?: ArxivSearchFilters` - Negated filter (ANDNOT)
+
+**Returns:**
+```typescript
+{
+  feed: {
+    id: string;
+    updated: string;
+    title: string;
+    link: string;
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+  };
+  entries: Array<{
+    id: string;
+    arxivId: string;
+    title: string;
+    summary: string;
+    published: string;
+    updated: string;
+    authors: Array<{ name: string; affiliation?: string }>;
+    categories: string[];
+    primaryCategory?: string;
+    links: Array<{ href: string; rel?: string; type?: string; title?: string }>;
+    doi?: string;
+    journalRef?: string;
+    comment?: string;
+  }>;
+}
+```
+
+## Examples
+
+### Search by title and author
+
+```typescript
+const result = await getArxivEntries({
+  search: {
+    title: ['machine learning'],
+    author: ['Geoffrey Hinton'],
+  },
+  maxResults: 5,
+});
+```
+
+### Fetch specific papers by ID
+
+Using the simpler `getArxivEntriesById` function:
+
+```typescript
+const result = await getArxivEntriesById(['2101.01234', '2101.05678']);
+```
+
+Or using `getArxivEntries`:
+
+```typescript
+const result = await getArxivEntries({
+  idList: ['2101.01234', '2101.05678'],
+});
+```
+
+### Complex search with OR and date range
+
+```typescript
+const result = await getArxivEntries({
+  search: {
+    or: [
+      { title: ['quantum'] },
+      { abstract: ['quantum'] },
+    ],
+    submittedDateRange: {
+      from: '202301010600',
+      to: '202401010600',
+    },
+  },
+  sortBy: 'submittedDate',
+  sortOrder: 'descending',
+});
+```
+
+### Fetch papers by ID with rate limiting
+
+```typescript
+const result = await getArxivEntriesById(
+  ['2101.01234', '2101.05678'],
+  {
+    rateLimit: {
+      tokensPerInterval: 1,
+      intervalMs: 3000, // 1 request per 3 seconds
+    },
+    timeoutMs: 15000,
+  }
+);
+```
+
+### Search with rate limiting
+
+```typescript
+const result = await getArxivEntries({
+  search: { title: ['neural networks'] },
+  rateLimit: {
+    tokensPerInterval: 1,
+    intervalMs: 3000, // 1 request per 3 seconds
+  },
+});
+```
+
+## Documentation
+
+### Generating API Documentation
+
+To generate browsable API documentation from the source code:
+
+```bash
+npm run docs:generate
+```
+
+This will create HTML documentation in the `docs/` directory. You can then view it locally:
+
+```bash
+npm run docs:serve
+```
+
+The generated documentation includes:
+- Complete API reference for all exported functions and types
+- Detailed parameter descriptions and examples
+- Type information and relationships
+- Search functionality
+
+### IDE IntelliSense
+
+All exported functions and types include JSDoc comments for enhanced IDE IntelliSense support. Hover over any exported symbol in your IDE to see inline documentation.
+
+## TypeScript Types
+
+All types are exported from the package:
+
+```typescript
+import type {
+  ArxivQueryOptions,
+  ArxivQueryResult,
+  ArxivSearchFilters,
+  ArxivEntry,
+  ArxivFeedMeta,
+  ArxivAuthor,
+  ArxivLink,
+  ArxivSortBy,
+  ArxivSortOrder,
+  ArxivRateLimitConfig,
+  ArxivDateRange,
+} from 'arxiv-api-wrapper';
+```
+
+## License
+
+ISC
+
+## Author
+
+Vilhelm Agdur
+
+## Repository
+
+https://github.com/vagdur/arxiv-api-wrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-api-wrapper",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Provides functions wrapping the arXiv API",
   "keywords": [
     "arxiv"
@@ -20,16 +20,18 @@
   "types": "./src/index.ts",
   "scripts": {
     "test": "vitest run --config tests/vitest.config.mts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run test && npm audit",
     "docs:generate": "typedoc",
     "docs:serve": "npx serve docs"
   },
   "dependencies": {
-    "fast-xml-parser": "^4.3.5"
+    "fast-xml-parser": "^5.3.5"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",
     "typedoc": "^0.26.0",
     "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "vitest": "^4.0.18"
   }
 }