Merge pull request #36 from IIIF-Commons/feature/v2.1

PNPM, Vitest, tsup
IIIF-Commons · Apr 9, 2024 · c3eae3e · c3eae3e
2 parents e38d15d + 8fa5728
commit c3eae3e
Show file tree

Hide file tree

Showing 42 changed files with 2,878 additions and 2,831 deletions.
diff --git a/.codesandbox/ci.json b/.codesandbox/ci.json
@@ -3,6 +3,5 @@
     "new",
     "simple-parser-2xxljf"
   ],
-  "buildCommand": "prepublishOnly",
-  "node": "16"
+  "node": "18"
 }
diff --git a/.eslintrc.json b/.eslintrc.json
diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml
@@ -1,37 +1,32 @@
-name: Yarn build + test
+name: Build
 
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+on: [push]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [ '16', '14' ]
+        node: ['18', '20']
 
     name: Node ${{ matrix.node }} build
     steps:
       - uses: actions/checkout@v1
-      - name: Get yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-      - uses: actions/cache@v1
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-${{ matrix.node }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
       - name: Setup node
         uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node }}
-      - run: yarn install --frozen-lockfile --non-interactive
-      - run: yarn run build
-      - run: yarn run test
-      - run: node pkg-tests/node-load.js
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: |
+            - recursive: true
+              args: [--frozen-lockfile, --strict-peer-dependencies]
+
+      - run: pnpm run build
+      - run: pnpm run test
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: node pkg-tests/node-load.cjs
       - run: node pkg-tests/node-load.mjs
-      - run: node pkg-tests/node-umd.js
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -13,24 +13,19 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@v2
         with:
-          node-version: '16.x'
+          node-version: '18.x'
 
-      - name: Get yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - uses: actions/cache@v1
+      - uses: pnpm/action-setup@v3
         with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn
-
-      - run: yarn install --frozen-lockfile --non-interactive
-
-      - run: yarn run build
+          version: 8
+          run_install: |
+            - recursive: true
+              args: [--frozen-lockfile, --strict-peer-dependencies]
 
-      - run: yarn run test
+      - run: pnpm build
+      - run: pnpm run test
+      - run: pnpm run lint
+      - run: pnpm run typecheck
 
   release:
     needs: [build]
@@ -41,24 +36,18 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@v2
         with:
-          node-version: '16.x'
+          node-version: '18.x'
 
       - name: Set tag
         id: tagName
         run: echo ::set-output name=tag::${GITHUB_REF#refs/*/}
 
-      - name: Get yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - uses: actions/cache@v1
+      - uses: pnpm/action-setup@v3
         with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn
-
-      - run: yarn install --frozen-lockfile --non-interactive
+          version: 8
+          run_install: |
+            - recursive: true
+              args: [--frozen-lockfile, --strict-peer-dependencies]
 
       - uses: JS-DevTools/npm-publish@v1
         with:

diff --git a/.iiif-sandbox.yml b/.iiif-sandbox.yml
diff --git a/README.md b/README.md
@@ -4,32 +4,167 @@
 npm i @iiif/parser
 ```
 
-### 2->3 Converter
+This is a parser and set of low-level utilities for the following IIIF Specifications:
 
-This is available as a standalone bundle. (~4kb gzipped)
+- [IIIF Presentation 3](https://iiif.io/api/presentation/3.0/) (current)
+- [IIIF Image 3](https://iiif.io/api/image/3.0/) (current)
+- [IIIF Presentation 2](https://iiif.io/api/presentation/2.1/)
 
-```js
-import { convertPresentation2 } from '@iiif/parser/presentation-2';
+These include:
+- [W3C Annotations](https://www.w3.org/TR/annotation-model/)
+- [Open Annotations](https://iiif.io/api/annex/openannotation/)
 
-const p3Manifest = convertPresentation2(p2Manifest);
-```
+
+> [!NOTE]  
+> A new version of the IIIF Presentation API is being developed (v4) which handles 3D content. This parser will
+> support this version soon. You can read about the additions [here](https://github.com/IIIF/3d/blob/main/temp-draft-4.md)
+
+### Features
+The features of this library are focussed on encoding the structure of all types of IIIF and providing utilities for extracting data from the IIIF or converting it into another format that is easier to develop with. The aim of the parser is to maximize the IIIF compatibility of other tools built on top of it.
+
+#### IIIF Presentation 3
+
+- **Empty types** for each resource (e.g. Manifest, Canvas) which can be used as starting points for creating IIIF
+- **Traverse** utility for walking through IIIF documents and running code at different "types"
+- **Normalize** utility which will:
+  - Add default empty defaults (null or empty array)
+  - Organize by type into Records
+  - Replace nested with references using ID/Type or SpecificResources
+- **Serializers** which take normalized data and output it again
+  - **Presentation v3 serializer**- outputs well-formed Presentation 3 JSON
+  - **Presentation v2 serializer** - outputs good-enough Presentation 2 JSON (missing features).
+- **Strict Upgrader** utility which can automatically fix Presentation 3 JSON that has issues. 
 
 
-### Basic usage
 ```js
 import { Traverse } from '@iiif/parser';
 
 // Or for presentation 2 resources
 // import { Traverse } from '@iiif/parser/presentation-2'; 
 
 const ids = [];
-const extractCanvasLabsl = new Traverse({
+const extractCanvasLabels = new Traverse({
   Canvas: [(canvas) => {
     ids.push(canvas.id); // string
   }],
 });
 
-extractCanvasLabsl.traverseUnknown(loadSomeManifest());
+extractCanvasLabels.traverseUnknown(loadSomeManifest());
 
 console.log(ids); // all canvas ids.
 ```
+
+#### IIIF Presentation 2
+- **Traverse** utility for walking through IIIF v2 documents and running code at different "types"
+- **Upgrader** utility built on-top of the Traverse utility for upgrading IIIF v2 to IIIF v3.
+
+The intention for IIIF Presentation 2 is to upgrade it to 3 and then work with that. The tooling will always offer and upgrade to the latest version and tools on top of that. 
+
+```ts
+import { Traverse, convertPresentation2  } from '@iiif/parser/presentation-2';
+
+convertPresentation2(p2); // to latest IIIF version
+
+const logAnnotations = new Traverse({
+  // Every type is a key on this record, with an array of functions to call
+  Annotation: [
+    anno => {
+      console.log(anno['@id']);
+
+      // Optionally return to replace the resource.
+    }
+  ]
+});
+
+logAnnotations.traverseManifest(someInputManifest); // Logs all annotation IDs.
+
+// Also an "all" traversal.
+const logAllIds = Traverse.all(resource => console.log(resource['@id']));
+
+logAllIds.traverseUnknown(someInput);
+
+```
+
+
+#### Image 3
+
+The Image 3 parser is adapted from an Image Server implementation, and supports:
+
+- Parsing of IIIF Image API request URLs (including info.json)
+  - Extracting region
+  - Extracting rotation
+  - Extracting size
+  - Extracting quality
+  - Extracting format
+- Parsing of IIIF profiles, and feature detection
+  - `isLevel0(service)`
+  - `supports(service, { extraQualities: ['grey'] })` helper which accepts a service and partial service to compare
+  - `imageServiceSupportsRequest()` helper that can validate IIIF image requests before you make them
+- Serializing of IIIF Image requests
+  - A custom structure for defining `region`, `size`, `quality` etc. and then creating a IIIF Image request URL.
+  - Support for Image 2.1 servers
+- Handful of utilities for IIIF Image 3
+  - extracting fixes sized images from an image service
+  - extracting fixed sizes from scale factors (full tiles)
+  - `canonicalServiceUrl()`, `getId()`, `getType()` and `isImageService()` for compatibility and validation
+
+```ts
+import { parseImageServiceRequest, imageServiceRequestInfo } from '@iiif/parser/image-3';
+import {  ImageService } from '@iiif/presentation-3';
+
+const parsed = parseImageServiceRequest(
+  'https://munch.emuseum.com/apis/iiif/image/v2/17261/full/max/0/default.jpg',
+  // Optionally provide a path, so the identifier can be extracted
+  'apis/iiif/image/v2'
+);
+
+// {
+//   "format": "jpg",
+//   "identifier": "17261",
+//   "originalPath": "/17261/full/max/0/default.jpg",
+//   "prefix": "apis/iiif/image/v2",
+//   "quality": "default",
+//   "region": {
+//     "full": true,
+//   },
+//   "rotation": {
+//     "angle": 0,
+//   },
+//   "scheme": "https",
+//   "server": "munch.emuseum.com",
+//   "size": {
+//     "confined": false,
+//     "max": true,
+//     "serialiseAsFull": false,
+//     "upscaled": false,
+//   },
+//   "type": "image",
+// }
+
+// Can be changed.
+parsed.rotation.angle = 90;
+
+const imageUrl = imageServiceRequestToString(parsed);
+// https://munch.emuseum.com/apis/iiif/image/v2/17261/full/max/90/default.jpg
+
+const infoJson = imageServiceRequestInfo(parsed);
+// https://munch.emuseum.com/apis/iiif/image/v2/17261/info.json
+
+
+const imageService: ImageService = await fetch(infoJson).then(r => r.json());
+
+// Likely true - as its supported by level0, level1 and level2
+const supportsSizes = supports(imageService, {
+  extraFeatures: ['sizeByWhListed']
+});
+```
+
+### Upgrader standalone
+
+Upgrades IIIF JSON to the latest IIIF Presentation version (current: 3).
+
+```ts
+import { upgrade } from '@iiif/parser/upgrader';
+
+upgrade(presentation2Manifest); // Presentation 3 Manifest or Collection
+```