arxiv-api-wrapper 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,209 @@
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-api-wrapper",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Provides functions wrapping the arXiv API",
   "keywords": [
     "arxiv"
@@ -19,12 +19,16 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
-    "test": "vitest run --config tests/vitest.config.mts"
+    "test": "vitest run --config tests/vitest.config.mts",
+    "docs:generate": "typedoc",
+    "docs:serve": "npx serve docs"
   },
   "dependencies": {
     "fast-xml-parser": "^4.3.5"
   },
   "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typedoc": "^0.26.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
   }

package/src/arxivAPIRead.ts

@@ -45,6 +45,40 @@ function joinAnd(parts: string[]): string {
   return parts.filter(Boolean).join('+AND+');
 }
 
+/**
+ * Builds an arXiv search query string from search filters.
+ * 
+ * This function converts the structured `ArxivSearchFilters` object into
+ * a query string compatible with the arXiv API search syntax. Multiple terms
+ * in the same field are combined with AND, and multiple fields are combined
+ * with AND. OR groups and negation (ANDNOT) are also supported.
+ * 
+ * @param filters - Search filters to convert to query string
+ * @returns URL-encoded query string ready for arXiv API
+ * 
+ * @example
+ * ```typescript
+ * const query = buildSearchQuery({
+ *   title: ['machine learning'],
+ *   author: ['Geoffrey Hinton'],
+ * });
+ * // Returns: "ti:\"machine learning\"+AND+au:\"Geoffrey Hinton\""
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Complex query with OR groups
+ * const query = buildSearchQuery({
+ *   or: [
+ *     { title: ['quantum'] },
+ *     { abstract: ['quantum'] },
+ *   ],
+ *   category: ['quant-ph'],
+ * });
+ * ```
+ * 
+ * @see {@link ArxivSearchFilters} for filter options
+ */
 export function buildSearchQuery(filters: ArxivSearchFilters): string {
   const parts: string[] = [];
   const phraseExact = filters.phraseExact;
@@ -110,6 +144,63 @@ function buildUrl(opts: ArxivQueryOptions): string {
   return `${ARXIV_BASE_URL}?${qs}`;
 }
 
+/**
+ * Queries the arXiv API and returns matching paper entries.
+ * 
+ * This is the main function for interacting with the arXiv API. It supports
+ * searching by various criteria, fetching specific papers by ID, pagination,
+ * sorting, rate limiting, and automatic retries with exponential backoff.
+ * 
+ * @param options - Query options including search filters, pagination, and request configuration
+ * @returns Promise resolving to query results with feed metadata and paper entries
+ * 
+ * @throws {Error} If the API request fails after all retries
+ * @throws {Error} If the API returns a non-2xx status code
+ * @throws {Error} If the API returns an empty response
+ * 
+ * @example
+ * ```typescript
+ * // Simple search
+ * const result = await getArxivEntries({
+ *   search: {
+ *     title: ['quantum computing'],
+ *     author: ['John Doe'],
+ *   },
+ *   maxResults: 10,
+ * });
+ * 
+ * console.log(`Found ${result.feed.totalResults} papers`);
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Fetch specific papers by ID
+ * const result = await getArxivEntries({
+ *   idList: ['2101.01234', '2101.05678'],
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // With rate limiting and custom timeout
+ * const result = await getArxivEntries({
+ *   search: { title: ['neural networks'] },
+ *   rateLimit: {
+ *     tokensPerInterval: 1,
+ *     intervalMs: 3000, // 1 request per 3 seconds
+ *   },
+ *   timeoutMs: 15000,
+ *   retries: 5,
+ * });
+ * ```
+ * 
+ * @see {@link ArxivQueryOptions} for all available options
+ * @see {@link ArxivQueryResult} for the return type structure
+ * @see {@link ArxivSearchFilters} for search filter options
+ */
 export async function getArxivEntries(options: ArxivQueryOptions): Promise<ArxivQueryResult> {
   const timeoutMs = options.timeoutMs ?? 10000;
   const retries = options.retries ?? 3;

package/src/index.ts

@@ -1,5 +1,46 @@
+/**
+ * @packageDocumentation
+ * 
+ * # arxiv-api-wrapper
+ * 
+ * A TypeScript package that provides a convenient wrapper around the arXiv API,
+ * enabling easy querying and parsing of arXiv papers.
+ * 
+ * ## 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)
+ * 
+ * ## 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}`);
+ * });
+ * ```
+ * 
+ * @module arxiv-api-wrapper
+ */
+
 // Main entry point for the arXiv API wrapper package
-export { getArxivEntries, buildSearchQuery } from './arxivAPIRead';
+export { getArxivEntries } from './arxivAPIRead';
 export type {
   ArxivQueryOptions,
   ArxivQueryResult,

package/src/types.ts

@@ -1,87 +1,265 @@
+/**
+ * Sort field options for arXiv query results.
+ */
 export type ArxivSortBy = 'relevance' | 'lastUpdatedDate' | 'submittedDate';
+
+/**
+ * Sort order direction for arXiv query results.
+ */
 export type ArxivSortOrder = 'ascending' | 'descending';
 
+/**
+ * Configuration for token bucket rate limiting.
+ * 
+ * @example
+ * ```typescript
+ * const rateLimit: ArxivRateLimitConfig = {
+ *   tokensPerInterval: 1,
+ *   intervalMs: 3000, // 1 request per 3 seconds
+ * };
+ * ```
+ */
 export interface ArxivRateLimitConfig {
+  /** Number of tokens (requests) allowed per interval */
   tokensPerInterval: number;
+  /** Interval duration in milliseconds */
   intervalMs: number;
 }
 
+/**
+ * Date range filter for arXiv queries.
+ * Dates must be in YYYYMMDDTTTT format (GMT timezone).
+ * 
+ * @example
+ * ```typescript
+ * const dateRange: ArxivDateRange = {
+ *   from: '202301010600',
+ *   to: '202401010600',
+ * };
+ * ```
+ */
 export interface ArxivDateRange {
+  /** Start date in YYYYMMDDTTTT format (GMT) */
   from: string; // YYYYMMDDTTTT (GMT)
+  /** End date in YYYYMMDDTTTT format (GMT) */
   to: string;   // YYYYMMDDTTTT (GMT)
 }
 
+/**
+ * Search filters for querying arXiv papers.
+ * Multiple terms in the same field are combined with AND.
+ * Multiple fields are combined with AND.
+ * 
+ * @example
+ * ```typescript
+ * const filters: ArxivSearchFilters = {
+ *   title: ['machine learning'],
+ *   author: ['Geoffrey Hinton'],
+ *   category: ['cs.LG'],
+ * };
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Complex query with OR groups
+ * const filters: ArxivSearchFilters = {
+ *   or: [
+ *     { title: ['quantum'] },
+ *     { abstract: ['quantum'] },
+ *   ],
+ *   submittedDateRange: {
+ *     from: '202301010600',
+ *     to: '202401010600',
+ *   },
+ * };
+ * ```
+ * 
+ * @see {@link ArxivDateRange} for date range format
+ */
 export interface ArxivSearchFilters {
+  /** Search terms to match in all fields */
   all?: string[];
+  /** Search terms to match in paper titles (arXiv field: ti:) */
   title?: string[]; // ti:
+  /** Search terms to match author names (arXiv field: au:) */
   author?: string[]; // au:
+  /** Search terms to match in abstracts (arXiv field: abs:) */
   abstract?: string[]; // abs:
+  /** Search terms to match in comments (arXiv field: co:) */
   comment?: string[]; // co:
+  /** Search terms to match in journal references (arXiv field: jr:) */
   journalRef?: string[]; // jr:
+  /** arXiv category codes to filter by (arXiv field: cat:) */
   category?: string[]; // cat:
+  /** Date range filter for submission dates (arXiv field: submittedDate:[from TO to]) */
   submittedDateRange?: ArxivDateRange; // submittedDate:[from TO to]
 
   // Composition
+  /** OR group: at least one of the subfilters must match */
   or?: ArxivSearchFilters[]; // grouped OR of subfilters
+  /** Negated filter: exclude papers matching this filter */
   andNot?: ArxivSearchFilters; // negated subfilter
 
   // Encoding behavior
+  /** If true, wrap each search term in quotes for exact phrase matching */
   phraseExact?: boolean; // wrap each term in quotes
 }
 
+/**
+ * Options for querying the arXiv API.
+ * 
+ * @example
+ * ```typescript
+ * const options: ArxivQueryOptions = {
+ *   search: {
+ *     title: ['quantum computing'],
+ *     author: ['John Doe'],
+ *   },
+ *   maxResults: 10,
+ *   sortBy: 'submittedDate',
+ *   sortOrder: 'descending',
+ * };
+ * ```
+ * 
+ * @see {@link ArxivSearchFilters} for search filter details
+ * @see {@link ArxivRateLimitConfig} for rate limiting configuration
+ */
 export interface ArxivQueryOptions {
+  /** List of arXiv IDs to fetch directly (e.g., ['2101.01234', '2101.05678']). If provided, search filters are ignored. */
   idList?: string[];
+  /** Search filters to query papers. Ignored if `idList` is provided. */
   search?: ArxivSearchFilters; // ignored if idList present
+  /** Pagination offset (0-based index) */
   start?: number; // 0-based
+  /** Maximum number of results to return (≤ 300 per arXiv API guidance) */
   maxResults?: number; // <= 300 per arXiv guidance
+  /** Field to sort results by */
   sortBy?: ArxivSortBy;
+  /** Sort order direction */
   sortOrder?: ArxivSortOrder;
+  /** Request timeout in milliseconds (default: 10000) */
   timeoutMs?: number; // default 10000
+  /** Number of retry attempts for failed requests (default: 3) */
   retries?: number; // default 3
+  /** Rate limiting configuration to respect arXiv API guidelines */
   rateLimit?: ArxivRateLimitConfig;
+  /** Custom User-Agent header for requests */
   userAgent?: string; // optional custom UA header
 }
 
+/**
+ * Link metadata for an arXiv paper entry.
+ * Links may point to the abstract page, PDF, source files, etc.
+ */
 export interface ArxivLink {
+  /** URL of the link */
   href: string;
+  /** Link relation type (e.g., 'alternate', 'related') */
   rel?: string;
+  /** MIME type of the linked resource */
   type?: string;
+  /** Human-readable title for the link */
   title?: string;
 }
 
+/**
+ * Author information for an arXiv paper.
+ */
 export interface ArxivAuthor {
+  /** Author's full name */
   name: string;
+  /** Author's institutional affiliation (if provided) */
   affiliation?: string;
 }
 
+/**
+ * Represents a single arXiv paper entry.
+ * 
+ * @example
+ * ```typescript
+ * const entry: ArxivEntry = {
+ *   id: 'http://arxiv.org/abs/2101.01234v2',
+ *   arxivId: '2101.01234v2',
+ *   title: 'Example Paper Title',
+ *   summary: 'Paper abstract...',
+ *   published: '2021-01-01T12:00:00Z',
+ *   updated: '2021-01-02T12:00:00Z',
+ *   authors: [{ name: 'John Doe', affiliation: 'University' }],
+ *   categories: ['cs.LG', 'cs.AI'],
+ *   primaryCategory: 'cs.LG',
+ *   links: [...],
+ * };
+ * ```
+ */
 export interface ArxivEntry {
+  /** Full URL to the paper's abstract page */
   id: string; // abs URL
+  /** arXiv ID including version (e.g., '2101.01234v2') */
   arxivId: string; // e.g., 2101.01234v2
+  /** Paper title */
   title: string;
+  /** Paper abstract/summary */
   summary: string;
+  /** Publication date (ISO 8601 format) */
   published: string;
+  /** Last update date (ISO 8601 format) */
   updated: string;
+  /** List of paper authors */
   authors: ArxivAuthor[];
+  /** arXiv category codes assigned to the paper */
   categories: string[];
+  /** Primary arXiv category code */
   primaryCategory?: string;
+  /** Links to abstract, PDF, source files, etc. */
   links: ArxivLink[];
+  /** Digital Object Identifier (if published elsewhere) */
   doi?: string;
+  /** Journal reference (if published) */
   journalRef?: string;
+  /** Author comments about the paper */
   comment?: string;
 }
 
+/**
+ * Metadata about the arXiv query feed/response.
+ */
 export interface ArxivFeedMeta {
+  /** Feed identifier */
   id: string;
+  /** Feed last update timestamp (ISO 8601 format) */
   updated: string;
+  /** Feed title */
   title: string;
+  /** Link to the query that generated this feed */
   link: string;
+  /** Total number of results matching the query */
   totalResults: number;
+  /** Starting index of results in this page (0-based) */
   startIndex: number;
+  /** Number of items per page in this response */
   itemsPerPage: number;
 }
 
+/**
+ * Complete result from an arXiv API query.
+ * 
+ * @example
+ * ```typescript
+ * const result: ArxivQueryResult = await getArxivEntries({
+ *   search: { title: ['machine learning'] },
+ *   maxResults: 10,
+ * });
+ * 
+ * console.log(`Found ${result.feed.totalResults} papers`);
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ */
 export interface ArxivQueryResult {
+  /** Feed metadata and pagination information */
   feed: ArxivFeedMeta;
+  /** Array of arXiv paper entries */
   entries: ArxivEntry[];
 }
 

package/typedoc.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "out": "docs",
+  "name": "arxiv-api-wrapper",
+  "readme": "./README.md",
+  "includeVersion": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "theme": "default",
+  "sort": ["source-order"],
+  "categorizeByGroup": true,
+  "categoryOrder": [
+    "Functions",
+    "Interfaces",
+    "Types"
+  ],
+  "gitRevision": "main",
+  "gitRemote": "origin",
+  "validation": {
+    "invalidLink": true,
+    "notDocumented": false
+  }
+}
+