arxiv-api-wrapper 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-api-wrapper",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Provides functions wrapping the arXiv API",
   "keywords": [
     "arxiv"

package/src/oaiClient.ts

@@ -33,6 +33,7 @@ import type {
 } from './oaiTypes.js';
 
 const OAI_BASE_URL = 'https://oaipmh.arxiv.org/oai';
+const OAI_EARLIEST_DATE = '2005-09-16';
 
 const DEFAULT_USER_AGENT = 'arxiv-api-wrapper/1.0 (+https://export.arxiv.org)';
 
@@ -53,7 +54,7 @@ interface OaiParams {
   resumptionToken?: string;
 }
 
-function hasValue(value: string | undefined): boolean {
+function hasValue(value: string | undefined): value is string {
   return value != null && value !== '';
 }
 
@@ -81,6 +82,40 @@ function throwResumptionTokenExclusiveError(context: 'request params' | 'list op
   );
 }
 
+function parseDatePrefix(dateValue: string): string | undefined {
+  const trimmed = dateValue.trim();
+  if (!trimmed) return undefined;
+  const match = /^(\d{4}-\d{2}-\d{2})(?:$|T\d{2}:\d{2}:\d{2}Z$)/.exec(trimmed);
+  return match?.[1];
+}
+
+function validateFromDateNotTooEarly(from: string | undefined): void {
+  if (!hasValue(from)) return;
+  const normalizedDate = parseDatePrefix(from);
+  if (!normalizedDate) return;
+  if (normalizedDate < OAI_EARLIEST_DATE) {
+    throw new OaiError(
+      'badArgument',
+      `Invalid list options: from=${from} is earlier than arXiv's earliest supported OAI datestamp ` +
+        `(${OAI_EARLIEST_DATE}). Use from >= ${OAI_EARLIEST_DATE} or omit from.`
+    );
+  }
+}
+
+function validateUntilDateNotTooLate(until: string | undefined): void {
+  if (!hasValue(until)) return;
+  const normalizedDate = parseDatePrefix(until);
+  if (!normalizedDate) return;
+  const todayUtc = new Date().toISOString().slice(0, 10);
+  if (normalizedDate > todayUtc) {
+    throw new OaiError(
+      'badArgument',
+      `Invalid list options: until=${until} is later than today's UTC date (${todayUtc}). ` +
+        'Use until <= today (UTC) or omit until.'
+    );
+  }
+}
+
 /** Build OAI-PMH request URL (exported for unit tests). */
 export function buildOaiUrl(verb: OaiVerb, params: OaiParams): string {
   if (hasResumptionTokenConflicts(params)) {
@@ -241,6 +276,8 @@ export async function oaiListIdentifiers(
   const from = listOptions?.from;
   const until = listOptions?.until;
   const set = listOptions?.set;
+  validateFromDateNotTooEarly(from);
+  validateUntilDateNotTooLate(until);
   const params: OaiParams = {};
   if (hasValue(resumptionToken)) {
     params.resumptionToken = resumptionToken;
@@ -272,6 +309,8 @@ export async function oaiListRecords(
   const from = listOptions?.from;
   const until = listOptions?.until;
   const set = listOptions?.set;
+  validateFromDateNotTooEarly(from);
+  validateUntilDateNotTooLate(until);
   const params: OaiParams = {};
   if (hasValue(resumptionToken)) {
     params.resumptionToken = resumptionToken;

package/tests/oai.test.ts

@@ -294,3 +294,58 @@ describe('resumptionToken validation', () => {
     });
   });
 });
+
+describe('from date validation', () => {
+  it('throws a local OaiError when from is earlier than arXiv minimum date', async () => {
+    await expect(
+      oaiListRecords('oai_dc', { from: '2005-09-15' })
+    ).rejects.toMatchObject({
+      name: 'OaiError',
+      code: 'badArgument',
+    });
+    await expect(oaiListRecords('oai_dc', { from: '2005-09-15' })).rejects.toThrow(
+      "earlier than arXiv's earliest supported OAI datestamp (2005-09-16)"
+    );
+  });
+
+  it('throws for earlier datetime form and allows earliest date', async () => {
+    await expect(
+      oaiListIdentifiers('oai_dc', { from: '2005-09-15T23:59:59Z' })
+    ).rejects.toMatchObject({
+      name: 'OaiError',
+      code: 'badArgument',
+    });
+    const url = buildOaiUrl('ListIdentifiers', { metadataPrefix: 'oai_dc', from: '2005-09-16' });
+    expect(url).toContain('from=2005-09-16');
+  });
+});
+
+describe('until date validation', () => {
+  it('throws a local OaiError when until is in the future', async () => {
+    const tomorrowUtc = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+
+    await expect(
+      oaiListRecords('oai_dc', { until: tomorrowUtc })
+    ).rejects.toMatchObject({
+      name: 'OaiError',
+      code: 'badArgument',
+    });
+    await expect(oaiListRecords('oai_dc', { until: tomorrowUtc })).rejects.toThrow(
+      "later than today's UTC date"
+    );
+  });
+
+  it('throws for future datetime form and allows today', async () => {
+    const tomorrowUtc = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    const todayUtc = new Date().toISOString().slice(0, 10);
+
+    await expect(
+      oaiListIdentifiers('oai_dc', { until: `${tomorrowUtc}T00:00:00Z` })
+    ).rejects.toMatchObject({
+      name: 'OaiError',
+      code: 'badArgument',
+    });
+    const url = buildOaiUrl('ListIdentifiers', { metadataPrefix: 'oai_dc', until: todayUtc });
+    expect(url).toContain(`until=${todayUtc}`);
+  });
+});