@allmaps/iiif-inspector 1.0.0-beta.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2026 Bert Spaan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @allmaps/iiif-inspector
+
+Inspect IIIF resources and extract useful metadata for Allmaps.
+
+## Usage
+
+```ts
+import { findYearInManifest } from '@allmaps/iiif-inspector'
+
+const year = findYearInManifest(manifest)
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { parseLanguageString } from './language-string.js';
+export { findBestYearInIIIFResource, findYearCandidatesInIIIFResource, findYearInCanvas, findYearInIIIFResource, findYearInManifest, findYearsInLanguageString, findYearsInMetadata, findYearsInValue, scoreYear } from './years.js';
+export type { IIIFInspectableResource, ScoredYearCandidate, YearCandidateOptions, YearCandidateSource, YearCandidate } from './years.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { parseLanguageString } from './language-string.js';
+export { findBestYearInIIIFResource, findYearCandidatesInIIIFResource, findYearInCanvas, findYearInIIIFResource, findYearInManifest, findYearsInLanguageString, findYearsInMetadata, findYearsInValue, scoreYear } from './years.js';

package/dist/language-string.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageString } from '@allmaps/iiif-parser';
+export declare function parseLanguageString(languageString?: LanguageString, preferredLanguage?: string): string;

package/dist/language-string.js

@@ -0,0 +1,18 @@
+export function parseLanguageString(languageString, preferredLanguage) {
+    if (!languageString) {
+        return '';
+    }
+    let strings = [];
+    if (preferredLanguage && languageString[preferredLanguage]) {
+        strings = languageString[preferredLanguage];
+    }
+    else if (languageString['none']) {
+        strings = languageString['none'];
+    }
+    else if (typeof languageString === 'object' && languageString !== null) {
+        if (Object.values(languageString)[0]) {
+            strings = Object.values(languageString)[0];
+        }
+    }
+    return strings.map((string) => String(string)).join(' ');
+}

package/dist/years.d.ts

@@ -0,0 +1,35 @@
+import type { Canvas as IIIFCanvas, LanguageString, Manifest as IIIFManifest, Metadata } from '@allmaps/iiif-parser';
+export type YearCandidateSource = 'navDate' | 'metadata' | 'label' | 'summary' | 'description' | 'value';
+export type YearCandidate = {
+    value: string;
+    year: number;
+    endYear?: number;
+    source?: YearCandidateSource;
+    metadataLabel?: string;
+    language?: string;
+    approximate?: boolean;
+};
+export type ScoredYearCandidate = YearCandidate & {
+    score: number;
+};
+export type YearCandidateOptions = {
+    source?: YearCandidateSource;
+    metadataLabel?: string;
+    language?: string;
+};
+export type IIIFInspectableResource = {
+    navDate?: Date;
+    metadata?: Metadata;
+    description?: LanguageString;
+    label?: LanguageString;
+    summary?: LanguageString;
+};
+export declare function scoreYear(candidate: YearCandidate): number;
+export declare function findYearsInLanguageString(languageString?: LanguageString, options?: Omit<YearCandidateOptions, 'language'>): YearCandidate[];
+export declare function findYearsInValue(value: string | number | boolean, options?: YearCandidateOptions): YearCandidate[];
+export declare function findYearInCanvas(canvas?: IIIFCanvas): number | undefined;
+export declare function findYearInManifest(manifest?: IIIFManifest): number | undefined;
+export declare function findYearInIIIFResource(iiifResource: IIIFInspectableResource): number | undefined;
+export declare function findBestYearInIIIFResource(iiifResource: IIIFInspectableResource): ScoredYearCandidate;
+export declare function findYearCandidatesInIIIFResource(iiifResource: IIIFInspectableResource): ScoredYearCandidate[];
+export declare function findYearsInMetadata(metadata?: Metadata): YearCandidate[];

package/dist/years.js

@@ -0,0 +1,246 @@
+const YEAR_MIN = 1500;
+const YEAR_MAX = 2200;
+const SOURCE_PENALTIES = {
+    navDate: -1000,
+    metadata: 100,
+    label: 260,
+    summary: 420,
+    description: 620,
+    value: 500
+};
+const DATE_METADATA_LABEL_PATTERNS = [
+    /\bdate\b/i,
+    /\byear\b/i,
+    /\bcreated?\b/i,
+    /\bcreation\b/i,
+    /\bissued?\b/i,
+    /\bpublished?\b/i,
+    /\bpublication\b/i,
+    /\btemporal\b/i,
+    /\bcoverage\b/i
+];
+const WEAK_DATE_METADATA_LABEL_PATTERNS = [
+    /\bpublisher\b/i,
+    /\bprovenance\b/i,
+    /\borigin\b/i
+];
+const NEGATIVE_METADATA_LABEL_PATTERNS = [
+    /\bidentifier\b/i,
+    /\bcall\s*number\b/i,
+    /\bshelf\s*mark\b/i,
+    /\bshelfmark\b/i,
+    /\baccession\b/i,
+    /\bdigitized?\b/i,
+    /\bmodified\b/i,
+    /\bright(s)?\b/i,
+    /\burl\b/i,
+    /\bpermalink\b/i,
+    /\blink\b/i,
+    /\blicen[cs]e\b/i
+];
+const NEGATIVE_VALUE_PATTERNS = [
+    /\bdigitized?\b/i,
+    /\bmodified\b/i,
+    /\baccessed\b/i,
+    /\bdownloaded\b/i,
+    /\bidentifier\b/i,
+    /\bpermalink\b/i,
+    /\blicen[cs]e\b/i
+];
+function isDateMetadataLabel(metadataLabel) {
+    return (metadataLabel &&
+        DATE_METADATA_LABEL_PATTERNS.some((pattern) => pattern.test(metadataLabel)));
+}
+function isWeakDateMetadataLabel(metadataLabel) {
+    return (metadataLabel &&
+        WEAK_DATE_METADATA_LABEL_PATTERNS.some((pattern) => pattern.test(metadataLabel)));
+}
+function isNegativeMetadataLabel(metadataLabel) {
+    return (metadataLabel &&
+        NEGATIVE_METADATA_LABEL_PATTERNS.some((pattern) => pattern.test(metadataLabel)));
+}
+function getMetadataLabelPenalty(candidate) {
+    if (candidate.source !== 'metadata') {
+        return 0;
+    }
+    if (isDateMetadataLabel(candidate.metadataLabel)) {
+        return -120;
+    }
+    else if (isWeakDateMetadataLabel(candidate.metadataLabel)) {
+        return 80;
+    }
+    else if (isNegativeMetadataLabel(candidate.metadataLabel)) {
+        return 650;
+    }
+    return 180;
+}
+function getValueContextPenalty(candidate) {
+    let penalty = 0;
+    if (NEGATIVE_VALUE_PATTERNS.some((pattern) => pattern.test(candidate.value))) {
+        penalty += 350;
+    }
+    if (candidate.approximate) {
+        penalty += 20;
+    }
+    return penalty;
+}
+function parseMetadataLabel(label) {
+    return Object.values(label)
+        .flat()
+        .map((value) => String(value))
+        .join(' ');
+}
+function isValidYear(year) {
+    return year > YEAR_MIN && year < YEAR_MAX;
+}
+function getTokenAtIndex(value, index) {
+    const before = value.slice(0, index);
+    const after = value.slice(index);
+    const start = Math.max(before.lastIndexOf(' '), before.lastIndexOf('\n'), before.lastIndexOf('\t'), before.lastIndexOf('"'), before.lastIndexOf("'"));
+    const endMatch = after.search(/[\s"'<>()[\]]/);
+    const end = endMatch === -1 ? value.length : index + endMatch;
+    return value.slice(start + 1, end);
+}
+function isYearInUrl(value, index) {
+    const token = getTokenAtIndex(value, index);
+    return /^https?:\/\//i.test(token) || /^www\./i.test(token);
+}
+function getFollowingRangeYear(value, index) {
+    const rangeMatch = value
+        .slice(index + 4)
+        .match(/^\s*(?:[-/–—]|\bto\b|\band\b)\s*(?<year>\d{4})\b/i);
+    const yearStr = rangeMatch?.groups?.year;
+    if (!yearStr) {
+        return;
+    }
+    const year = parseInt(yearStr, 10);
+    if (isValidYear(year)) {
+        return year;
+    }
+}
+function isApproximateYear(value, index) {
+    const prefix = value.slice(Math.max(0, index - 12), index);
+    return /\b(ca\.?|circa|around|about|approx\.?)\s*$/i.test(prefix);
+}
+// Prefer explicit IIIF and metadata date signals over incidental years in long
+// descriptions. Earlier years and shorter values only break ties after source
+// and context have been considered.
+export function scoreYear(candidate) {
+    const sourcePenalty = SOURCE_PENALTIES[candidate.source ?? 'value'];
+    const metadataLabelPenalty = getMetadataLabelPenalty(candidate);
+    const valueContextPenalty = getValueContextPenalty(candidate);
+    const valueLengthPenalty = Math.min(candidate.value.length, 400) * 2;
+    const yearPenalty = (candidate.year - YEAR_MIN) * 0.05;
+    const score = sourcePenalty +
+        metadataLabelPenalty +
+        valueContextPenalty +
+        valueLengthPenalty +
+        yearPenalty;
+    return score;
+}
+export function findYearsInLanguageString(languageString, options = {}) {
+    if (!languageString) {
+        return [];
+    }
+    return Object.entries(languageString)
+        .map(([language, values]) => values.map((value) => findYearsInValue(value, {
+        ...options,
+        language
+    })))
+        .flat(2);
+}
+export function findYearsInValue(value, options = {}) {
+    const regex = /\b(?<year>\d{4})\b/g;
+    const stringValue = String(value);
+    const candidates = [];
+    for (const match of stringValue.matchAll(regex)) {
+        const yearStr = match.groups?.year;
+        if (yearStr) {
+            const year = parseInt(yearStr, 10);
+            if (isValidYear(year) && !isYearInUrl(stringValue, match.index)) {
+                const endYear = getFollowingRangeYear(stringValue, match.index);
+                const approximate = isApproximateYear(stringValue, match.index);
+                candidates.push({
+                    value: stringValue,
+                    year,
+                    ...(endYear ? { endYear } : {}),
+                    ...(approximate ? { approximate } : {}),
+                    ...options
+                });
+            }
+        }
+    }
+    return candidates;
+}
+export function findYearInCanvas(canvas) {
+    if (canvas) {
+        return findYearInIIIFResource(canvas);
+    }
+}
+export function findYearInManifest(manifest) {
+    if (manifest) {
+        return findYearInIIIFResource(manifest);
+    }
+}
+export function findYearInIIIFResource(iiifResource) {
+    const candidate = findBestYearInIIIFResource(iiifResource);
+    if (candidate) {
+        return candidate.year;
+    }
+}
+export function findBestYearInIIIFResource(iiifResource) {
+    return findYearCandidatesInIIIFResource(iiifResource)[0];
+}
+export function findYearCandidatesInIIIFResource(iiifResource) {
+    const navDateYears = iiifResource.navDate
+        ? [
+            {
+                value: iiifResource.navDate.toISOString(),
+                year: iiifResource.navDate.getFullYear(),
+                source: 'navDate'
+            }
+        ]
+        : [];
+    const metadataYears = findYearsInMetadata(iiifResource.metadata);
+    const descriptionYears = findYearsInLanguageString(iiifResource.description, {
+        source: 'description'
+    });
+    const labelYears = findYearsInLanguageString(iiifResource.label, {
+        source: 'label'
+    });
+    const summaryYears = findYearsInLanguageString(iiifResource.summary, {
+        source: 'summary'
+    });
+    return [
+        ...navDateYears,
+        ...metadataYears,
+        ...descriptionYears,
+        ...labelYears,
+        ...summaryYears
+    ]
+        .map((year) => ({
+        ...year,
+        score: scoreYear(year)
+    }))
+        .sort((a, b) => a.score - b.score || a.year - b.year);
+}
+export function findYearsInMetadata(metadata) {
+    if (!metadata) {
+        return [];
+    }
+    const allYears = [];
+    for (const metadataItem of metadata) {
+        const metadataLabel = parseMetadataLabel(metadataItem.label);
+        const values = Object.values(metadataItem.value).flat();
+        for (const value of values) {
+            const years = findYearsInValue(value, {
+                source: 'metadata',
+                metadataLabel
+            });
+            if (years.length > 0) {
+                allYears.push(...years);
+            }
+        }
+    }
+    return allYears;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@allmaps/iiif-inspector",
+  "version": "1.0.0-beta.2",
+  "author": {
+    "name": "Bert Spaan",
+    "email": "hello@bertspaan.nl",
+    "url": "https://bertspaan.nl"
+  },
+  "description": "Inspect IIIF resources and extract useful metadata",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allmaps/allmaps.git",
+    "directory": "packages/iiif-inspector"
+  },
+  "homepage": "https://allmaps.org",
+  "keywords": [
+    "allmaps",
+    "iiif",
+    "inspector"
+  ],
+  "scripts": {
+    "watch": "tsc --watch --noCheck",
+    "build": "tsc --noCheck",
+    "types": "tsc --noEmit",
+    "test": "NODE_ENV=test vitest run",
+    "lint": "prettier --ignore-path ../../.gitignore --check src test && eslint src test --ext .js,.ts",
+    "documentation": "remark . --output --use remark-api",
+    "format": "prettier --ignore-path ../../.gitignore --write src test"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@allmaps/iiif-parser": "^1.0.0-beta.49"
+  },
+  "devDependencies": {
+    "@allmaps/types": "^1.0.0-beta.24",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.3",
+    "remark-api": "^1.1.0",
+    "remark-cli": "^12.0.1",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "8.0.16",
+    "vitest": "^4.1.8"
+  },
+  "gitHead": "c1a72e7f5c7d228c6cd55e9611fe8e0dd7dd2274"
+}