exifreader 4.54.0 → 4.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +398 -27
  2. package/bin/analyze.js +139 -9
  3. package/bin/build-pages.js +21 -35
  4. package/bin/cli.js +81 -13
  5. package/bin/generate-tag-modules.js +287 -0
  6. package/dist/exif-reader.js +1 -1
  7. package/dist/exif-reader.js.map +1 -1
  8. package/exif-reader.d.ts +213 -38
  9. package/package.json +71 -11
  10. package/src/composable/brand.js +10 -0
  11. package/src/composable/composition-tag-filter.js +97 -0
  12. package/src/composable/composition.js +195 -0
  13. package/src/composable/core.d.ts +148 -0
  14. package/src/composable/core.js +526 -0
  15. package/src/composable/exif-block-reader.js +197 -0
  16. package/src/composable/formats/avif.js +19 -0
  17. package/src/composable/formats/gif.js +28 -0
  18. package/src/composable/formats/heic.js +19 -0
  19. package/src/composable/formats/iso-bmff-file-reader.js +14 -0
  20. package/src/composable/formats/jpeg.js +55 -0
  21. package/src/composable/formats/jxl.js +30 -0
  22. package/src/composable/formats/png.js +187 -0
  23. package/src/composable/formats/tiff.js +18 -0
  24. package/src/composable/formats/webp.js +28 -0
  25. package/src/composable/formats/xml.js +18 -0
  26. package/src/composable/formats.d.ts +17 -0
  27. package/src/composable/formats.js +17 -0
  28. package/src/composable/group-helpers.js +129 -0
  29. package/src/composable/groups/canon.js +26 -0
  30. package/src/composable/groups/composite.js +43 -0
  31. package/src/composable/groups/exif.js +48 -0
  32. package/src/composable/groups/gps.js +75 -0
  33. package/src/composable/groups/icc.js +52 -0
  34. package/src/composable/groups/iptc.js +86 -0
  35. package/src/composable/groups/maker-notes.js +21 -0
  36. package/src/composable/groups/mpf.js +25 -0
  37. package/src/composable/groups/pentax.js +34 -0
  38. package/src/composable/groups/photoshop.js +18 -0
  39. package/src/composable/groups/thumbnail.js +131 -0
  40. package/src/composable/groups/xmp.js +118 -0
  41. package/src/composable/groups.d.ts +20 -0
  42. package/src/composable/groups.js +105 -0
  43. package/src/composable/iptc-block-reader.js +44 -0
  44. package/src/composable/read-view.js +165 -0
  45. package/src/composable/tag-binding-name.js +17 -0
  46. package/src/composable/tags/exif.d.ts +295 -0
  47. package/src/composable/tags/exif.js +396 -0
  48. package/src/composable/tags/iptc.d.ts +84 -0
  49. package/src/composable/tags/iptc.js +109 -0
  50. package/src/composable/value-budget.js +24 -0
  51. package/src/composite.js +2 -2
  52. package/src/decompression.js +60 -0
  53. package/src/engine.js +50 -106
  54. package/src/errors.js +8 -2
  55. package/src/exif-reader.d.ts +8 -0
  56. package/src/exif-reader.js +112 -763
  57. package/src/file-loaders.js +74 -1
  58. package/src/file-tags.js +9 -9
  59. package/src/image-header.js +13 -47
  60. package/src/iptc-tag-names-descriptions.js +334 -0
  61. package/src/iptc-tag-names.js +50 -306
  62. package/src/iptc-tags.js +41 -27
  63. package/src/jfif-tags.js +9 -9
  64. package/src/load-auto.js +2 -2
  65. package/src/loadview-pipeline.js +52 -192
  66. package/src/node-require.js +15 -2
  67. package/src/png-text-tags.js +5 -3
  68. package/src/tag-filter-config.js +24 -15
  69. package/src/tag-filter.js +15 -3
  70. package/src/tag-names-0th-ifd-descriptions.js +232 -0
  71. package/src/tag-names-0th-ifd.js +49 -173
  72. package/src/tag-names-common.js +263 -211
  73. package/src/tag-names-exif-ifd-descriptions.js +249 -0
  74. package/src/tag-names-exif-ifd.js +55 -187
  75. package/src/tag-names-gps-ifd-descriptions.js +156 -0
  76. package/src/tag-names-gps-ifd.js +39 -146
  77. package/src/tag-names-utils.js +28 -3
  78. package/src/tags-helpers.js +6 -2
  79. package/src/types.js +2 -0
  80. package/src/unsupported-format-error.js +21 -0
  81. package/src/utils.js +22 -85
  82. package/src/xmp-tag-names.js +42 -21
  83. package/webpack.config.js +1 -1
package/README.md CHANGED
@@ -11,9 +11,10 @@ If you use the `length: 'auto'` option, ExifReader reads only the bytes
11
11
  that contain metadata, **well under 1 ms per file** for typical phone JPEGs
12
12
  and **over 95% less bandwidth**.
13
13
 
14
- ExifReader is highly and easily configurable and the resulting bundle can be as
15
- small as **~9 KiB** (Brotli-compressed) if you're only interested in a few tags
16
- (e.g. date and/or GPS values).
14
+ You can compose a reader from only the formats, groups and tags you read. A
15
+ reader of the date and the GPS position of JPEG files bundles to
16
+ **about 12 KiB** (esbuild, minified, Brotli). See [the composable
17
+ API](#composable-api).
17
18
 
18
19
  ExifReader supports module formats ESM, AMD, CommonJS, and globals and can
19
20
  therefore easily be used from Webpack, RequireJS, Browserify, Node etc.
@@ -65,7 +66,9 @@ Table of Contents
65
66
  1. [Support](#support)
66
67
  2. [Installation](#installation)
67
68
  3. [Usage](#usage)
68
- 4. [Configure a Custom Build](#configure-a-custom-build)
69
+ - [Composable API](#composable-api)
70
+ - [Migrating to the composable API](#migrating-to-the-composable-api)
71
+ 4. [Configure a Custom Build (deprecated)](#configure-a-custom-build)
69
72
  5. [Notes](#notes)
70
73
  6. [Client/Browser Support](#clientbrowser-support)
71
74
  7. [Examples](#examples)
@@ -114,7 +117,15 @@ After that, the transpiled, concatenated and minified ES5 file will be in the
114
117
 
115
118
  ### Type definitions
116
119
 
117
- Type definitions for TypeScript are included in the package.
120
+ Type definitions for TypeScript are included in the package. Each subpath of
121
+ the [composable API](#composable-api) (`exifreader/core`, `exifreader/formats`,
122
+ `exifreader/groups`, `exifreader/tags/exif` and `exifreader/tags/iptc`) ships
123
+ its own definitions next to its module, which TypeScript finds with
124
+ `moduleResolution` set to `bundler`, `node16` or `nodenext`. A CommonJS file
125
+ can import them only with `module` set to `nodenext` or `node20` (see
126
+ Toolchains in [the composable API](#composable-api)). `exifreader/core` also
127
+ exports the types of the arguments to `load`, `LoadInput` and `LoadOptions`, and
128
+ of its result, `Tags` and `ExpandedTags`.
118
129
 
119
130
  Usage
120
131
  -----
@@ -156,6 +167,24 @@ requirejs(['/path/to/exif-reader.js'], function (ExifReader) {
156
167
  <script src="/path/to/exif-reader.js"></script>
157
168
  ```
158
169
 
170
+ > **In a browser app?** If you only need a few tags, compose a reader with only
171
+ > what you read. This one reads the date and the GPS position of JPEG files:
172
+ >
173
+ > ```javascript
174
+ > import {createReader} from 'exifreader/core';
175
+ > import {jpeg} from 'exifreader/formats';
176
+ > import {gps} from 'exifreader/groups';
177
+ > import {DateTimeOriginal} from 'exifreader/tags/exif';
178
+ >
179
+ > const reader = createReader({formats: [jpeg], groups: [gps], tags: [DateTimeOriginal]});
180
+ > const tags = await reader.load(file);
181
+ > // tags.exif.DateTimeOriginal, tags.gps.Latitude, tags.gps.Longitude
182
+ > ```
183
+ >
184
+ > It bundles to about 12 KiB, against about 42 KiB for the default entry
185
+ > (esbuild, minified, Brotli). See [the composable API](#composable-api) for the
186
+ > rest. For everything else, start with the default entry as shown above.
187
+
159
188
  ### Loading tags
160
189
 
161
190
  There are two ways to load the tags. Either have ExifReader do the loading of
@@ -255,6 +284,9 @@ You can filter which tags are returned by using `includeTags` and/or
255
284
  - An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
256
285
  excluding that group. The group will not be returned and ExifReader will skip
257
286
  parsing it.
287
+ - A group's value can be `true`, an array of selectors, or `false` to leave the
288
+ group out. That is useful with a boolean variable, e.g.
289
+ `includeTags: { exif: true, xmp: includeXmp }`.
258
290
 
259
291
  **Examples**
260
292
 
@@ -281,7 +313,7 @@ const tags = ExifReader.load(fileBuffer, {
281
313
  **Filtering groups**
282
314
 
283
315
  The group keys follow the same concept as the output when `expanded: true` is
284
- used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
316
+ used. (The `thumbnail` group controls the top-level `thumbnail` value.)
285
317
 
286
318
  For PNG, filtering is done with the `png` group only. (The `pngFile` and
287
319
  `pngText` groups exist in `expanded` output today, but `png` is the filtering
@@ -303,7 +335,7 @@ key and those groups will be deprecated later.)
303
335
  | `gif` | GIF tags. | no |
304
336
  | `gps` | Computed GPS group (only when `expanded: true`). | no |
305
337
  | `composite` | Composite tags (e.g. FieldOfView). | no |
306
- | `thumbnail` | Top-level `Thumbnail` output. | no |
338
+ | `thumbnail` | Top-level `thumbnail` output. | no |
307
339
 
308
340
  **Important: dependency tags**
309
341
 
@@ -329,7 +361,7 @@ output is still filtered.
329
361
  Filtering removes parsed tags only, not the raw data they were parsed from.
330
362
  Some tags hold such data, for example `xmp._raw` (with `expanded: true`), the
331
363
  Exif `ApplicationNotes` and `IPTC-NAA` tags, the MPF `Images`, PNG text tags
332
- and `Thumbnail`. When filtering for privacy, list the tags you want in
364
+ and `thumbnail`. When filtering for privacy, list the tags you want in
333
365
  `includeTags` (by name, not `true`) instead of excluding the ones you do not.
334
366
 
335
367
  #### Unknown tags
@@ -752,7 +784,22 @@ npm override, a Yarn resolution or a pnpm override pins `@xmldom/xmldom` below
752
784
 
753
785
  #### Using React Native
754
786
 
755
- Import ExifReader like this:
787
+ React Native 0.79 and later (Metro 0.82 and later) resolve the subpaths of the
788
+ [composable API](#composable-api), so you can import `exifreader/core` and the
789
+ other subpaths directly and pass the same buffer as below to
790
+ `await reader.load(fileBuffer)`. React Native has no `DOMParser`, so a reader
791
+ with `xmp` needs a parser passed to `createReader` in its `domParser` key (see
792
+ [Parsing XMP tags when not in a DOM
793
+ environment](#parsing-xmp-tags-when-not-in-a-dom-environment)).
794
+
795
+ Metro does not tree shake, so it loads every format and group the imported
796
+ subpaths reference. Under Metro 0.88, a reader of JPEG files with `gps` and two
797
+ tags is over 230 KiB raw and 60 KiB gzip. That is still smaller than the
798
+ default entry under Metro (over 250 KiB and 75 KiB), but esbuild bundles the
799
+ one-tag `Single tags` example of the [composable API](#composable-api) to about
800
+ 39 KiB and 13 KiB.
801
+
802
+ With the default entry, or an older Metro, import ExifReader like this:
756
803
 
757
804
  ```javascript
758
805
  import ExifReader from './node_modules/exifreader/src/exif-reader.js';
@@ -793,18 +840,18 @@ values](https://github.com/mattiasw/ExifReader/issues/378#issuecomment-230270598
793
840
 
794
841
  ### Using the thumbnail
795
842
 
796
- The thumbnail and its details will be accessible through `tags['Thumbnail']`.
843
+ The thumbnail and its details will be accessible through `tags['thumbnail']`.
797
844
  There is information about e.g. width and height, and the thumbnail image data
798
- is stored in `tags['Thumbnail'].image`.
845
+ is stored in `tags['thumbnail'].image`.
799
846
 
800
847
  How you use it is going to depend on your environment. For a web browser you can
801
- either use the raw byte data in `tags['Thumbnail'].image` and use it the way you
802
- want, or you can use the helper property `tags['Thumbnail'].base64` that is a
848
+ either use the raw byte data in `tags['thumbnail'].image` and use it the way you
849
+ want, or you can use the helper property `tags['thumbnail'].base64` that is a
803
850
  base64 representation of the image. It can be used for a data URI like this:
804
851
 
805
852
  ```javascript
806
853
  const tags = ExifReader.load(fileBuffer);
807
- imageElement.src = 'data:image/jpg;base64,' + tags['Thumbnail'].base64;
854
+ imageElement.src = 'data:image/jpg;base64,' + tags['thumbnail'].base64;
808
855
  ```
809
856
 
810
857
  If you're using node, you can store it as a new file like this:
@@ -812,19 +859,317 @@ If you're using node, you can store it as a new file like this:
812
859
  ```javascript
813
860
  const fs = require('fs');
814
861
  const tags = ExifReader.load(fileBuffer);
815
- fs.writeFileSync('/path/to/new/thumbnail.jpg', Buffer.from(tags['Thumbnail'].image));
862
+ fs.writeFileSync('/path/to/new/thumbnail.jpg', Buffer.from(tags['thumbnail'].image));
816
863
  ```
817
864
 
865
+ On `ExifReader.load` and `loadView`, `tags['Thumbnail']` is the old name of the
866
+ same value and is removed in v5. Until then it is the one that `Object.keys` and
867
+ `JSON.stringify` list, since `thumbnail` is not enumerable there, so a copy of
868
+ the result (spread, `Object.assign`, `structuredClone` or a JSON round trip)
869
+ keeps only `Thumbnail`. When a file has a PNG text or XMP tag named
870
+ `thumbnail`, that tag keeps the key in the flat result, so code that has to
871
+ handle such files reads `Thumbnail` until v5. A reader from the
872
+ [composable API](#composable-api) returns only `thumbnail`.
873
+
818
874
  See the [examples site](https://mattiasw.github.io/ExifReader/) for more
819
875
  details.
820
876
 
821
877
  ### Optimizing build size
822
878
 
823
- The most important step will be to [use a custom
824
- build](#configure-a-custom-build) so please do that.
879
+ #### Composable API
880
+
881
+ Import only the formats, groups and tags you read, and your bundler leaves out
882
+ the rest.
883
+
884
+ **Whole groups.** This reader reads the Exif and XMP tags of JPEG and HEIC
885
+ files:
825
886
 
826
- If you are using Webpack 4 or lower and are only targeting web browsers, make
827
- sure to add this to your Webpack config (probably the `webpack.config.js` file):
887
+ ```javascript
888
+ import {createReader} from 'exifreader/core';
889
+ import {jpeg, heic} from 'exifreader/formats';
890
+ import {exif, xmp} from 'exifreader/groups';
891
+
892
+ const reader = createReader({formats: [jpeg, heic], groups: [exif, xmp]});
893
+ const tags = await reader.load(file);
894
+ ```
895
+
896
+ **Single tags.** This one reads only the date and the GPS position of JPEG
897
+ files:
898
+
899
+ ```javascript
900
+ import {createReader} from 'exifreader/core';
901
+ import {jpeg} from 'exifreader/formats';
902
+ import {gps} from 'exifreader/groups';
903
+ import {DateTimeOriginal} from 'exifreader/tags/exif';
904
+
905
+ const reader = createReader({formats: [jpeg], groups: [gps], tags: [DateTimeOriginal]});
906
+ const tags = await reader.load(file);
907
+ // tags.exif.DateTimeOriginal, tags.gps.Latitude, tags.gps.Longitude
908
+ ```
909
+
910
+ The output is grouped, since a reader is built from groups. `expanded: false`
911
+ gives flat output, for code that moves over from `ExifReader.load` (see
912
+ [Migrating to the composable API](#migrating-to-the-composable-api) for what
913
+ differs). In flat output the name `thumbnail` is reserved for the
914
+ thumbnail, so a PNG text or XMP tag of that name is read from the grouped
915
+ output (`tags.png.thumbnail`, `tags.xmp.thumbnail`). `tags.gps` (`Latitude`,
916
+ `Longitude` and `Altitude`) is only in the grouped output. In a flat load, `gps`
917
+ therefore adds no GPS values at all: a reader composed with `gps` alone returns
918
+ only the `file` and `jfif` tags for a JPEG file. For GPS values in flat output,
919
+ import `GPSLatitude`, `GPSLatitudeRef`, `GPSLongitude`, `GPSLongitudeRef`,
920
+ `GPSAltitude` and `GPSAltitudeRef` from `exifreader/tags/exif` and pass them in
921
+ `tags`. A flat load then has `GPSLatitude` with its unsigned decimal
922
+ description, and the `Ref` tags carry the hemisphere and whether the altitude is
923
+ below sea level (see [Notes](#notes) and the [GPS section](#gps)).
924
+
925
+ A group or tag the file does not hold is absent from the result, so
926
+ `tags.exif?.DateTimeOriginal?.description` covers every case.
927
+
928
+ **What a group brings.** Each group reads the Exif tags it needs: `gps` the six
929
+ GPS tags its values come from, `xmp` `ApplicationNotes`, `iptc` `IPTC-NAA`,
930
+ `icc` `ICC_Profile`, `photoshop` `ImageSourceData` and `PhotoshopSettings`,
931
+ `makerNotes`, `canon` and `pentax` `MakerNote` and `Make`, `thumbnail`
932
+ `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength`, and `composite` the
933
+ focal length and pixel dimension tags it computes its values from. The reader
934
+ reads those tags but returns them only when they are also in `tags` or the
935
+ whole `exif` group is composed: with `makerNotes`, for example, add `Make` to
936
+ `tags` to get `exif.Make`. A format brings its own tags: every format gives
937
+ `file` (`FileType`, and the image details where the format has them), and
938
+ `jpeg` adds `jfif`, `png` adds `png`, `webp` adds `riff` and `gif` adds `gif`.
939
+ The grouped output of a composed reader has `png` alone, which holds every tag
940
+ of `pngFile` and `pngText`, not those two groups.
941
+
942
+ **Tags.** `tags` takes Exif and IPTC tags, imported from `exifreader/tags/exif`
943
+ and `exifreader/tags/iptc`. With `iptc` not in `groups`, a reader composed with
944
+ IPTC tags returns only those, and it reads the block's `Coded Character Set`
945
+ for the text encoding even when that tag is not in `tags`. MPF tags come only
946
+ with the whole `mpf` group. Three IPTC tags come only with the whole `iptc`
947
+ group: `ObjectData Preview File Format` and `Record 2 destination` (dataset
948
+ 2:200), whose name depends on the length of the value, so no import can select
949
+ it, and `ObjectData Preview File Format Version` (2:201), whose description is
950
+ read from dataset 2:200. A tag's import name differs from its key in the result
951
+ when its name has characters a JavaScript name cannot hold, so `ByLine` is read
952
+ as `tags.iptc['By-line']` and `SubLocation` as `tags.iptc['Sub-location']`.
953
+ The keys in the result are the same as in `ExifReader.load`.
954
+ On a composed reader, a repeatable IPTC dataset such as `Keywords` is always an
955
+ array of tag objects, also when the file holds it once. In the flat output an
956
+ XMP tag of the same name replaces it, as it does in `ExifReader.load`.
957
+
958
+ **Subpaths.**
959
+
960
+ | Subpath | Exports |
961
+ |---|---|
962
+ | `exifreader/core` | `createReader`, `errors` (`UnsupportedFormatError`), `tagFilter` |
963
+ | `exifreader/formats` | `tiff`, `jpeg`, `png`, `heic`, `avif`, `jxl`, `webp`, `gif`, `xml` (XMP sidecar files; returns only `FileType` without `xmp` in `groups`), `allFormats` |
964
+ | `exifreader/groups` | `exif`, `iptc`, `xmp`, `icc`, `photoshop`, `mpf`, `makerNotes`, `canon`, `pentax`, `gps`, `composite`, `thumbnail`, `allGroups` |
965
+ | `exifreader/tags/exif`, `exifreader/tags/iptc` | One export per tag, named after the tag with every character that cannot be in a JavaScript name removed and the letter after it upper-cased (`By-line` becomes `ByLine`, `GPS Info IFD Pointer` becomes `GPSInfoIFDPointer`) |
966
+
967
+ `makerNotes` holds every maker note decoder and grows with new releases.
968
+ `canon` and `pentax` hold one each.
969
+
970
+ Pass these values as they are imported. A copy or an altered copy of a format,
971
+ group or tag is not supported.
972
+
973
+ **Everything.** `createReader({formats: allFormats, groups: allGroups})` reads
974
+ everything (`allGroups` has `makerNotes`, not `canon` or `pentax`). Filtering
975
+ these arrays skips parsing but does not shrink the bundle, since the bundler
976
+ cannot see which entries you keep. Import by name instead. Composing `heic`
977
+ without `avif` saves little (under 0.1 KiB).
978
+
979
+ **Loading.** `reader.load` takes the image bytes or a `Blob` or `File`:
980
+
981
+ | You have | Call |
982
+ |---|---|
983
+ | A `File` from `<input type="file">` | `reader.load(file)`; for the first n bytes, `reader.load(file.slice(0, n))` |
984
+ | A path in Node | `reader.load(await readFile(path))` (`readFile` from `node:fs/promises`) |
985
+ | A path in Node, the first n bytes only | `reader.load((await openAsBlob(path)).slice(0, n))` (`openAsBlob` from `node:fs`) |
986
+ | A path in Bun | `reader.load(Bun.file(path))` |
987
+ | A URL | `reader.load(await (await fetch(url)).arrayBuffer())` |
988
+ | A `Response` | `reader.load(await response.arrayBuffer())` |
989
+ | A `ReadableStream` | `reader.load(await new Response(stream).arrayBuffer())` |
990
+ | Bytes: an `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, typed array such as `Uint8Array`, or Node `Buffer` | `reader.load(bytes)` |
991
+
992
+ `reader.load` always returns a Promise and never throws: every failure is a
993
+ rejection. It does not take strings or URLs, and it has no `length` or `async`
994
+ option (both reject). Passing `domParser` or `decompress` to `reader.load`
995
+ rejects too, as both go to `createReader`. The options it takes are `expanded`,
996
+ `includeUnknown`, `computed`, `includeOffsets`, `includeTags` and `excludeTags`;
997
+ the first four take only `true`, `false` or `undefined`, and any other value
998
+ rejects.
999
+ `expanded: false` gives the flat output, and `includeOffsets` needs no
1000
+ `expanded` (it does nothing with `expanded: false`).
1001
+
1002
+ **Errors.** Input that no composed format recognizes rejects with
1003
+ `UnsupportedFormatError`, so a reader of JPEG files only rejects a PNG file
1004
+ that way. The message names the formats of the reader in detection order: the
1005
+ JPEG-only reader below rejects with `reader.load: none of this reader's formats
1006
+ (jpeg) recognizes the input: it is in another format or is not an image`. Check
1007
+ for it with `error instanceof errors.UnsupportedFormatError`,
1008
+ using the `errors` of the entry the reader came from (`exifreader/core` for
1009
+ `createReader`, `ExifReader.errors` for the default entry, which under Node is
1010
+ the bundled `dist` file with its own copy of the class), or with
1011
+ `error.name === 'UnsupportedFormatError'`:
1012
+
1013
+ ```javascript
1014
+ import {createReader, errors} from 'exifreader/core';
1015
+ import {jpeg} from 'exifreader/formats';
1016
+ import {exif} from 'exifreader/groups';
1017
+
1018
+ const reader = createReader({formats: [jpeg], groups: [exif]});
1019
+ try {
1020
+ const tags = await reader.load(file);
1021
+ } catch (error) {
1022
+ if (error instanceof errors.UnsupportedFormatError) {
1023
+ // Not a JPEG file.
1024
+ }
1025
+ }
1026
+ ```
1027
+
1028
+ **XMP outside browsers.** Node, Bun, Deno, web workers and React Native have no
1029
+ `DOMParser`. With `xmp` composed, pass one to `createReader` in its `domParser`
1030
+ key (see [Parsing XMP tags when not in a DOM
1031
+ environment](#parsing-xmp-tags-when-not-in-a-dom-environment)):
1032
+
1033
+ ```javascript
1034
+ import {createReader} from 'exifreader/core';
1035
+ import {jpeg} from 'exifreader/formats';
1036
+ import {xmp} from 'exifreader/groups';
1037
+ import {DOMParser, onErrorStopParsing} from '@xmldom/xmldom';
1038
+
1039
+ const reader = createReader({formats: [jpeg], groups: [xmp], domParser: new DOMParser({onError: onErrorStopParsing})});
1040
+ const tags = await reader.load(data);
1041
+ ```
1042
+
1043
+ Without one, `reader.load` rejects with a message naming `domParser`. The check
1044
+ runs at load, so creating the reader where there is no `DOMParser`, such as
1045
+ during server rendering, does not throw. A composed reader never loads
1046
+ `@xmldom/xmldom` by itself.
1047
+
1048
+ **Decompression.** Custom Brotli or deflate functions and `maxDecompressedSize`
1049
+ go to `createReader` in its `decompress` key, the object that [Custom
1050
+ decompression](#custom-decompression) and [Limiting decompressed metadata
1051
+ size](#limiting-decompressed-metadata-size) describe for `ExifReader.load`. The
1052
+ limit applies to each `reader.load` call on its own:
1053
+
1054
+ ```javascript
1055
+ import zlib from 'node:zlib';
1056
+ import {createReader} from 'exifreader/core';
1057
+ import {jxl} from 'exifreader/formats';
1058
+ import {exif} from 'exifreader/groups';
1059
+
1060
+ const reader = createReader({
1061
+ formats: [jxl],
1062
+ groups: [exif],
1063
+ decompress: {
1064
+ brotli: (data, {maxOutputLength}) => zlib.brotliDecompressSync(data, {maxOutputLength}),
1065
+ maxDecompressedSize: 16 * 1024 * 1024
1066
+ }
1067
+ });
1068
+ ```
1069
+
1070
+ **Filtering.** `includeTags` and `excludeTags` need `tagFilter`, imported from
1071
+ `exifreader/core`, in `createReader`. Without it, `reader.load` rejects with a
1072
+ message naming the option. With it, `reader.load` also rejects an option that
1073
+ is not an object keyed by group, a key that is not a group (a misspelt one such
1074
+ as `exiff`), and a group value other than `true`, `false` or an array of tag
1075
+ names or ids. A group the reader does not compose is not an error: it is absent
1076
+ from the result. The options narrow what the reader composes and never
1077
+ add to it. See [Filtering tags](#filtering-tags-includetags--excludetags) for
1078
+ their shapes.
1079
+
1080
+ ```javascript
1081
+ import {createReader, tagFilter} from 'exifreader/core';
1082
+ import {jpeg} from 'exifreader/formats';
1083
+ import {exif, mpf} from 'exifreader/groups';
1084
+
1085
+ const reader = createReader({formats: [jpeg], groups: [exif, mpf], tagFilter});
1086
+ const tags = await reader.load(file, {excludeTags: {mpf: true}});
1087
+ ```
1088
+
1089
+ **Types.** In TypeScript, the grouped result of `reader.load` has only the
1090
+ groups and tags the reader composes, so `tags.gps` does not compile on a reader
1091
+ without `gps`. Each group has only its own tag names, so `tags.exif?.Headline`,
1092
+ an IPTC name, does not compile either. `includeTags` and `excludeTags` compile
1093
+ only on a reader created with `tagFilter` (type options built before the call
1094
+ as `LoadOptions<false>` for a reader without it). A table whose contents
1095
+ TypeScript cannot see, such as `allFormats`, `allGroups` or an array typed
1096
+ `Format[]` or `Group[]`, gives every group instead, typed as the `ExpandedTags`
1097
+ of `exifreader/core`. The flat output is typed `Tags` on every reader.
1098
+
1099
+ **Runtime.** The subpaths are published as source, not transpiled. The code is
1100
+ ES2015, and the `composite` group also uses the ES2016 `**` operator. A reader
1101
+ uses these platform APIs when it needs them: `Promise` for every load;
1102
+ `TextDecoder` for text in IPTC, XMP and decompressed data and for the Windows XP
1103
+ tags; `DecompressionStream` for compressed metadata in PNG and JPEG XL files,
1104
+ unless `decompress` gives the functions; `DOMParser` for `xmp`, unless
1105
+ `domParser` is given; `btoa` for the `base64` of a thumbnail or an MPF image;
1106
+ and `Blob` only when one is passed to `reader.load`.
1107
+
1108
+ **Toolchains.** The subpaths are ES modules only, resolved through the
1109
+ package's `exports` map. They work with webpack 5, Vite, Rollup with
1110
+ `@rollup/plugin-node-resolve`, esbuild, Parcel 2 with `packageExports` enabled,
1111
+ Bun, Deno, Metro 0.82 (React Native 0.79), TypeScript with `moduleResolution`
1112
+ set to `bundler`, `node16` or `nodenext`, and Node with `import` (`require()`
1113
+ needs Node 20.19 or later on Node 20, or 22.12 or later). Some toolchains need
1114
+ extra setup or have limits:
1115
+
1116
+ - **TypeScript.** A CommonJS importer (a `.cts` file, or a `.ts` file in a
1117
+ package without `"type": "module"`) gets TS1479 on the subpath imports with
1118
+ `module` set to `node16` or `node18`. It needs `module` set to `nodenext`
1119
+ (TypeScript 5.8 or later) or `node20` (TypeScript 5.9 or later). An ES module
1120
+ importer works with all of them.
1121
+ - **Jest.** Jest 28 to 30 fail with their default configuration, since Jest
1122
+ does not transform `node_modules`. They work with a Babel transform plus
1123
+ `transformIgnorePatterns: ['/node_modules/(?!exifreader/)']`, or with
1124
+ `--experimental-vm-modules` when the test files are ES modules themselves.
1125
+ - **eslint-plugin-import.** With its default resolver it reports
1126
+ `import/no-unresolved` on the subpaths, since that resolver does not read
1127
+ `exports`.
1128
+ - **Parcel.** Parcel 2.16.4 resolves the subpaths with `packageExports` enabled
1129
+ but leaves unreferenced code in the bundle: the `Single tags` example is
1130
+ about 20 KiB gzip there against 13 KiB with esbuild.
1131
+ - **CommonJS-compiled consumers.** A consumer compiled to CommonJS before
1132
+ bundling (`require('exifreader/core')`) loses tree shaking under esbuild and
1133
+ Vite 8 (a JPEG reader with `DateTimeOriginal`: over 120 KiB raw against
1134
+ 37 KiB). webpack 5, Rspack and `bun build` keep it.
1135
+ - **No tree shaking.** Without a tree-shaking bundler (Metro, unbundled Node,
1136
+ Deno or Bun), every format and group the imported subpaths reference is
1137
+ loaded.
1138
+
1139
+ #### Migrating to the composable API
1140
+
1141
+ A reader from `createReader` reads the same tags as `ExifReader.load` and
1142
+ describes them the same way. What differs when you move over from
1143
+ `ExifReader.load` or from a custom build:
1144
+
1145
+ | | `ExifReader.load` | A reader from `createReader` |
1146
+ |---|---|---|
1147
+ | Output | Flat by default, grouped with `expanded: true` | Grouped by default, flat with `expanded: false` |
1148
+ | Return value | The tags, or a Promise when it loads the file or with `async: true` | Always a Promise |
1149
+ | Input | Bytes, a `File`, a path or a URL | Bytes, a `Blob` or a `File` (see **Loading** for a path or a URL) |
1150
+ | Part of a file | The `length` option | Slice it first: `reader.load(file.slice(0, n))` |
1151
+ | `domParser` and `decompress` | Options of `load` | Passed to `createReader` |
1152
+ | XMP outside browsers | Looks for `@xmldom/xmldom` when no `domParser` is given | Needs `domParser`; nothing is looked up |
1153
+ | `includeTags` and `excludeTags` | Always available | Need `tagFilter` from `exifreader/core` in `createReader` |
1154
+ | Options | An unknown option is ignored, and any truthy value turns an option on | An unknown option rejects, and so does a value other than `true`, `false` or `undefined` |
1155
+ | PNG groups | `png`, `pngFile` and `pngText` | `png` |
1156
+ | A repeatable IPTC dataset such as `Keywords` | A tag when the file holds it once, an array when it holds several | Always an array |
1157
+ | A group with no tags | `{}` | Absent |
1158
+ | Thumbnail | `tags.thumbnail`, and `tags.Thumbnail` until v5 | `tags.thumbnail` |
1159
+ | `base64` of the thumbnail and MPF images | From `Buffer` or `btoa` | From `btoa`; `undefined` where there is none |
1160
+ | Errors | `ExifReader.errors` | `errors` from `exifreader/core` |
1161
+ | Published code | A UMD `dist` file, transpiled to ES5 | ES modules, not transpiled (see **Runtime**) |
1162
+ | Custom build | The `exifreader` key in `package.json` and `npx exifreader build` | Imports; `npx exifreader analyze --imports <images>` prints them |
1163
+
1164
+ #### Default entry
1165
+
1166
+ The [custom build](#configure-a-custom-build) was the previous way to a smaller
1167
+ bundle. It still works in v4, but it is deprecated and will be removed in v5, so
1168
+ use the composable API above instead.
1169
+
1170
+ If you use the default entry (`import ExifReader from 'exifreader'`) with
1171
+ Webpack 4 or lower and are only targeting web browsers, make sure to add this to
1172
+ your Webpack config (probably the `webpack.config.js` file):
828
1173
 
829
1174
  ```javascript
830
1175
  node: {
@@ -841,13 +1186,27 @@ Configure a Custom Build
841
1186
 
842
1187
  Configuring a custom build can reduce the bundle size significantly.
843
1188
 
844
- **NOTE 1:** This functionality is in beta but should work fine. Please file an
845
- issue if you're having problems or ideas on how to make it better.
1189
+ **NOTE 1:** The custom build was the previous way to a small bundle. It is still
1190
+ supported in v4, but it is deprecated and will be removed in v5. The
1191
+ [composable API](#composable-api) replaces it.
846
1192
 
847
1193
  **NOTE 2:** This only changes the built file (`exifreader/dist/exif-reader.js`),
848
1194
  not the source code. That means it's not possible to use the ES module (from the
849
1195
  `src` folder) or any tree shaking to get the benefit of a custom build. Tree
850
- shaking will actually have close to no effect at all here so don't rely on it.
1196
+ shaking has close to no effect on a custom build, so don't rely on it.
1197
+
1198
+ Which file a plain `import ExifReader from 'exifreader'` or
1199
+ `require('exifreader')` resolves to depends on the tool:
1200
+
1201
+ - `dist/exif-reader.js`, which picks up a custom build: Node, Bun, Deno, React
1202
+ Native's Metro (native platforms), webpack with `target: 'node'` and esbuild
1203
+ with `platform: 'node'`.
1204
+ - `src/exif-reader.js`, which never picks up a custom build: webpack 5, Vite,
1205
+ Parcel 2 and Metro when they build for the web, Rollup with
1206
+ `@rollup/plugin-node-resolve` and esbuild with `platform: 'browser'`.
1207
+
1208
+ If you bundle for the browser and use a custom build, import the built file
1209
+ directly: `import ExifReader from 'exifreader/dist/exif-reader';`.
851
1210
 
852
1211
  This is for npm and yarn users that use the built file. To specify what
853
1212
  functionality you want you can either use include pattern (start with an empty
@@ -873,7 +1232,7 @@ almost half the size of the full one (non-gzipped)):
873
1232
  ```
874
1233
 
875
1234
  **Example 2:** Only include TIFF files, and the Exif `DateTime` tag and the GPS
876
- tags (resulting bundle will be ~19 % of a gzipped full build):
1235
+ tags (resulting bundle will be about a third of a gzipped full build):
877
1236
 
878
1237
  ```javascript
879
1238
  "exifreader": {
@@ -931,7 +1290,9 @@ It reads the images with the full library and prints the smallest `include`
931
1290
  configuration that reads everything found in them: the file formats, the Exif
932
1291
  and IPTC tags, and the XMP, ICC, Photoshop, maker note, MPF and thumbnail
933
1292
  groups. Add `--write` to put it in your `package.json`, replacing any
934
- `include` or `exclude` section there, then run `npx exifreader build`. To
1293
+ `include` or `exclude` section there, then run `npx exifreader build`. Add
1294
+ `--imports` instead to print the equivalent `createReader` imports of the
1295
+ [composable API](#composable-api) in place of the configuration. To
935
1296
  analyze and build in one step, and then check the result:
936
1297
 
937
1298
  ```bash
@@ -1044,7 +1405,11 @@ Notes
1044
1405
  - In Exif data, the full GPS information is split into two different tags for
1045
1406
  each direction: the coordinate value (`GPSLatitude`, `GPSLongitude`) and the
1046
1407
  reference value (`GPSLatitudeRef`, `GPSLongitudeRef`). Use the references to
1047
- know whether the coordinate is north/south and east/west. Often you will see
1408
+ know whether the coordinate is north/south and east/west. The `description`
1409
+ of `GPSLatitude`, `GPSLongitude`, `GPSDestLatitude` and `GPSDestLongitude`
1410
+ is the decimal coordinate as a number, unsigned, with the reference tag
1411
+ giving the hemisphere. It is `NaN` when the value holds fewer than three
1412
+ `[numerator, denominator]` pairs. Often you will see
1048
1413
  north and east represented as positive values, and south and west
1049
1414
  represented as negative values (e.g. in Google Maps). This setup is also
1050
1415
  used for the altitude using `GPSAltitude` and `GPSAltitudeRef` where the
@@ -1086,7 +1451,11 @@ Tips
1086
1451
  will load a lot of files and storing the tags. It can be really large for
1087
1452
  some manufacturers. See the
1088
1453
  [examples site](https://mattiasw.github.io/ExifReader/) to see how you can
1089
- do that.
1454
+ do that. On a reader from the [composable API](#composable-api), leaving
1455
+ `makerNotes` out of `groups` skips decoding the maker notes, but a whole
1456
+ `exif` group still returns the raw `MakerNote` tag. Compose the Exif tags
1457
+ you need by name instead, or drop it with
1458
+ `excludeTags: {exif: ['MakerNote']}` on a reader composed with `tagFilter`.
1090
1459
  - In some cases it can make sense to only load the beginning of the image
1091
1460
  file since that is where the metadata is located. It's unfortunately not
1092
1461
  possible to know how big the metadata will be in an image, but if you limit
@@ -1101,7 +1470,9 @@ Tips
1101
1470
  especially impactful when combined with `length: 'auto'` (multi-x
1102
1471
  speedup, see that section), but it also lets a numeric `length`
1103
1472
  boundary land well before the sub-image. Regular Exif/XMP/ICC tags are
1104
- unaffected.
1473
+ unaffected. On a reader from the [composable API](#composable-api), leave
1474
+ `mpf` out of `groups`, or pass `excludeTags: {mpf: true}` to a reader
1475
+ composed with `mpf` and `tagFilter`.
1105
1476
 
1106
1477
  Known Limitations
1107
1478
  -----------------