@storyteller-platform/epub 0.4.6 → 0.4.7

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 (6) hide show
  1. package/README.md +80 -19
  2. package/dist/index.cjs +7 -0
  3. package/dist/index.d.cts +16 -1
  4. package/dist/index.d.ts +16 -1
  5. package/dist/index.js +7 -0
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -326,7 +326,7 @@ Defined in:
326
326
  > **\[dispose\]**(): `void`
327
327
 
328
328
  Defined in:
329
- [epub/index.ts:2493](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2493)
329
+ [epub/index.ts:2529](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2529)
330
330
 
331
331
  ##### Returns
332
332
 
@@ -420,7 +420,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
420
420
  > **addManifestItem**(`item`, `contents`, `encoding`): `Promise`\<`void`\>
421
421
 
422
422
  Defined in:
423
- [epub/index.ts:2189](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2189)
423
+ [epub/index.ts:2225](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2225)
424
424
 
425
425
  Create a new manifest item and write its contents to a new entry.
426
426
 
@@ -449,7 +449,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
449
449
  > **addManifestItem**(`item`, `contents`, `encoding`): `Promise`\<`void`\>
450
450
 
451
451
  Defined in:
452
- [epub/index.ts:2194](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2194)
452
+ [epub/index.ts:2230](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2230)
453
453
 
454
454
  Create a new manifest item and write its contents to a new entry.
455
455
 
@@ -478,7 +478,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
478
478
  > **addManifestItem**(`item`, `contents`): `Promise`\<`void`\>
479
479
 
480
480
  Defined in:
481
- [epub/index.ts:2199](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2199)
481
+ [epub/index.ts:2235](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2235)
482
482
 
483
483
  Create a new manifest item and write its contents to a new entry.
484
484
 
@@ -506,7 +506,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
506
506
  > **addMetadata**(`entry`): `Promise`\<`void`\>
507
507
 
508
508
  Defined in:
509
- [epub/index.ts:2311](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2311)
509
+ [epub/index.ts:2347](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2347)
510
510
 
511
511
  Add a new metadata entry to the Epub.
512
512
 
@@ -588,7 +588,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
588
588
  > [`XmlElement`](#xmlelement)\<`"?xml"`\>)[]\>
589
589
 
590
590
  Defined in:
591
- [epub/index.ts:2017](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2017)
591
+ [epub/index.ts:2051](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2051)
592
592
 
593
593
  Create a new XHTML document with the given body and head.
594
594
 
@@ -610,7 +610,7 @@ Create a new XHTML document with the given body and head.
610
610
  > **discardAndClose**(): `void`
611
611
 
612
612
  Defined in:
613
- [epub/index.ts:2420](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2420)
613
+ [epub/index.ts:2456](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2456)
614
614
 
615
615
  ##### Returns
616
616
 
@@ -931,6 +931,17 @@ If there is no dc:date element, returns null.
931
931
 
932
932
  https://www.w3.org/TR/epub-33/#sec-opf-dcdate
933
933
 
934
+ #### getRootfile()
935
+
936
+ > **getRootfile**(): `Promise`\<`string`\>
937
+
938
+ Defined in:
939
+ [epub/index.ts:540](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L540)
940
+
941
+ ##### Returns
942
+
943
+ `Promise`\<`string`\>
944
+
934
945
  #### getSpineItems()
935
946
 
936
947
  > **getSpineItems**(): `Promise`\<[`ManifestItem`](#manifestitem)[]\>
@@ -1048,6 +1059,56 @@ If there is no dc:type element, returns null.
1048
1059
 
1049
1060
  https://www.w3.org/TR/epub-33/#sec-opf-dctype
1050
1061
 
1062
+ #### readFileContents()
1063
+
1064
+ ##### Call Signature
1065
+
1066
+ > **readFileContents**(`href`, `relativeTo?`):
1067
+ > `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
1068
+
1069
+ Defined in:
1070
+ [epub/index.ts:1992](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1992)
1071
+
1072
+ Retrieve the contents of a file, given its href.
1073
+
1074
+ Optionally takes the href that this href should be resolved relative to, and an
1075
+ encoding parameter.
1076
+
1077
+ ###### Parameters
1078
+
1079
+ | Parameter | Type | Description |
1080
+ | ------------- | -------- | -------------------------------- |
1081
+ | `href` | `string` | The href of the file to retrieve |
1082
+ | `relativeTo?` | `string` | - |
1083
+
1084
+ ###### Returns
1085
+
1086
+ `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
1087
+
1088
+ ##### Call Signature
1089
+
1090
+ > **readFileContents**(`href`, `relativeTo`, `encoding`): `Promise`\<`string`\>
1091
+
1092
+ Defined in:
1093
+ [epub/index.ts:1993](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1993)
1094
+
1095
+ Retrieve the contents of a file, given its href.
1096
+
1097
+ Optionally takes the href that this href should be resolved relative to, and an
1098
+ encoding parameter.
1099
+
1100
+ ###### Parameters
1101
+
1102
+ | Parameter | Type | Description |
1103
+ | ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1104
+ | `href` | `string` | The href of the file to retrieve |
1105
+ | `relativeTo` | `undefined` \| `string` | - |
1106
+ | `encoding` | `"utf-8"` | Optional - Must be the string "utf-8". If provided, the function will encode the data into a unicode string. Otherwise, the data will be returned as a byte array. |
1107
+
1108
+ ###### Returns
1109
+
1110
+ `Promise`\<`string`\>
1111
+
1051
1112
  #### readItemContents()
1052
1113
 
1053
1114
  ##### Call Signature
@@ -1055,7 +1116,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctype
1055
1116
  > **readItemContents**(`id`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
1056
1117
 
1057
1118
  Defined in:
1058
- [epub/index.ts:1989](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1989)
1119
+ [epub/index.ts:2023](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2023)
1059
1120
 
1060
1121
  Retrieve the contents of a manifest item, given its id.
1061
1122
 
@@ -1078,7 +1139,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
1078
1139
  > **readItemContents**(`id`, `encoding`): `Promise`\<`string`\>
1079
1140
 
1080
1141
  Defined in:
1081
- [epub/index.ts:1990](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1990)
1142
+ [epub/index.ts:2024](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2024)
1082
1143
 
1083
1144
  Retrieve the contents of a manifest item, given its id.
1084
1145
 
@@ -1104,7 +1165,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
1104
1165
  > **readXhtmlItemContents**(`id`, `as?`): `Promise`\<[`ParsedXml`](#parsedxml)\>
1105
1166
 
1106
1167
  Defined in:
1107
- [epub/index.ts:2050](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2050)
1168
+ [epub/index.ts:2086](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2086)
1108
1169
 
1109
1170
  Retrieves the contents of an XHTML item, given its manifest id.
1110
1171
 
@@ -1128,7 +1189,7 @@ https://www.w3.org/TR/epub-33/#sec-xhtml
1128
1189
  > **readXhtmlItemContents**(`id`, `as`): `Promise`\<`string`\>
1129
1190
 
1130
1191
  Defined in:
1131
- [epub/index.ts:2051](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2051)
1192
+ [epub/index.ts:2087](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2087)
1132
1193
 
1133
1194
  Retrieves the contents of an XHTML item, given its manifest id.
1134
1195
 
@@ -1229,7 +1290,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
1229
1290
  > **removeManifestItem**(`id`): `Promise`\<`void`\>
1230
1291
 
1231
1292
  Defined in:
1232
- [epub/index.ts:2146](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2146)
1293
+ [epub/index.ts:2182](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2182)
1233
1294
 
1234
1295
  ##### Parameters
1235
1296
 
@@ -1246,7 +1307,7 @@ Defined in:
1246
1307
  > **removeMetadata**(`predicate`): `Promise`\<`void`\>
1247
1308
 
1248
1309
  Defined in:
1249
- [epub/index.ts:2395](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2395)
1310
+ [epub/index.ts:2431](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2431)
1250
1311
 
1251
1312
  Remove one or more metadata entries.
1252
1313
 
@@ -1321,7 +1382,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
1321
1382
  > **replaceMetadata**(`predicate`, `entry`): `Promise`\<`void`\>
1322
1383
 
1323
1384
  Defined in:
1324
- [epub/index.ts:2350](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2350)
1385
+ [epub/index.ts:2386](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2386)
1325
1386
 
1326
1387
  Replace a metadata entry with a new one.
1327
1388
 
@@ -1348,7 +1409,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-metadata
1348
1409
  > **saveAndClose**(): `Promise`\<`void`\>
1349
1410
 
1350
1411
  Defined in:
1351
- [epub/index.ts:2436](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2436)
1412
+ [epub/index.ts:2472](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2472)
1352
1413
 
1353
1414
  Write the current contents of the Epub to a new EPUB archive on disk.
1354
1415
 
@@ -1583,7 +1644,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctype
1583
1644
  > **updateManifestItem**(`id`, `newItem`): `Promise`\<`void`\>
1584
1645
 
1585
1646
  Defined in:
1586
- [epub/index.ts:2262](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2262)
1647
+ [epub/index.ts:2298](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2298)
1587
1648
 
1588
1649
  Update the manifest entry for an existing item.
1589
1650
 
@@ -1612,7 +1673,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-manifest
1612
1673
  > **writeItemContents**(`id`, `contents`): `Promise`\<`void`\>
1613
1674
 
1614
1675
  Defined in:
1615
- [epub/index.ts:2098](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2098)
1676
+ [epub/index.ts:2134](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2134)
1616
1677
 
1617
1678
  Write new contents for an existing manifest item, specified by its id.
1618
1679
 
@@ -1639,7 +1700,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
1639
1700
  > **writeItemContents**(`id`, `contents`, `encoding`): `Promise`\<`void`\>
1640
1701
 
1641
1702
  Defined in:
1642
- [epub/index.ts:2099](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2099)
1703
+ [epub/index.ts:2135](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2135)
1643
1704
 
1644
1705
  Write new contents for an existing manifest item, specified by its id.
1645
1706
 
@@ -1667,7 +1728,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
1667
1728
  > **writeXhtmlItemContents**(`id`, `contents`): `Promise`\<`void`\>
1668
1729
 
1669
1730
  Defined in:
1670
- [epub/index.ts:2138](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2138)
1731
+ [epub/index.ts:2174](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2174)
1671
1732
 
1672
1733
  Write new contents for an existing XHTML item, specified by its id.
1673
1734
 
package/dist/index.cjs CHANGED
@@ -1548,6 +1548,13 @@ ${JSON.stringify(element, null, 2)}`
1548
1548
  const startPath = (0, import_path.dirname)(from);
1549
1549
  return (0, import_path.resolve)(this.extractPath, startPath, href);
1550
1550
  }
1551
+ async readFileContents(href, relativeTo, encoding) {
1552
+ const rootfile = await this.getRootfile();
1553
+ const from = relativeTo ? this.resolveHref(rootfile, relativeTo) : rootfile;
1554
+ const path = this.resolveHref(from, href);
1555
+ const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
1556
+ return itemEntry;
1557
+ }
1551
1558
  async readItemContents(id, encoding) {
1552
1559
  const rootfile = await this.getRootfile();
1553
1560
  const manifest = await this.getManifest();
package/dist/index.d.cts CHANGED
@@ -184,7 +184,7 @@ declare class Epub {
184
184
  static from(pathOrData: string | Uint8Array): Promise<Epub>;
185
185
  private removeEntry;
186
186
  private getFileData;
187
- private getRootfile;
187
+ getRootfile(): Promise<string>;
188
188
  private migratePackageDocument;
189
189
  private getPackageDocument;
190
190
  private getPackageElement;
@@ -580,6 +580,21 @@ declare class Epub {
580
580
  * Returns a Zip Entry path for an HREF
581
581
  */
582
582
  private resolveHref;
583
+ /**
584
+ * Retrieve the contents of a file, given its href.
585
+ *
586
+ * Optionally takes the href that this href should be resolved relative to,
587
+ * and an encoding parameter.
588
+ *
589
+ * @param href The href of the file to retrieve
590
+ * @param [relitaveTo] Optional - The href to resolve this href relative to.
591
+ * Use if resolving a relative href from a file other than the package document.
592
+ * @param [encoding] Optional - Must be the string "utf-8". If provided,
593
+ * the function will encode the data into a unicode string.
594
+ * Otherwise, the data will be returned as a byte array.
595
+ */
596
+ readFileContents(href: string, relativeTo?: string): Promise<Uint8Array>;
597
+ readFileContents(href: string, relativeTo: string | undefined, encoding: "utf-8"): Promise<string>;
583
598
  /**
584
599
  * Retrieve the contents of a manifest item, given its id.
585
600
  *
package/dist/index.d.ts CHANGED
@@ -184,7 +184,7 @@ declare class Epub {
184
184
  static from(pathOrData: string | Uint8Array): Promise<Epub>;
185
185
  private removeEntry;
186
186
  private getFileData;
187
- private getRootfile;
187
+ getRootfile(): Promise<string>;
188
188
  private migratePackageDocument;
189
189
  private getPackageDocument;
190
190
  private getPackageElement;
@@ -580,6 +580,21 @@ declare class Epub {
580
580
  * Returns a Zip Entry path for an HREF
581
581
  */
582
582
  private resolveHref;
583
+ /**
584
+ * Retrieve the contents of a file, given its href.
585
+ *
586
+ * Optionally takes the href that this href should be resolved relative to,
587
+ * and an encoding parameter.
588
+ *
589
+ * @param href The href of the file to retrieve
590
+ * @param [relitaveTo] Optional - The href to resolve this href relative to.
591
+ * Use if resolving a relative href from a file other than the package document.
592
+ * @param [encoding] Optional - Must be the string "utf-8". If provided,
593
+ * the function will encode the data into a unicode string.
594
+ * Otherwise, the data will be returned as a byte array.
595
+ */
596
+ readFileContents(href: string, relativeTo?: string): Promise<Uint8Array>;
597
+ readFileContents(href: string, relativeTo: string | undefined, encoding: "utf-8"): Promise<string>;
583
598
  /**
584
599
  * Retrieve the contents of a manifest item, given its id.
585
600
  *
package/dist/index.js CHANGED
@@ -1515,6 +1515,13 @@ ${JSON.stringify(element, null, 2)}`
1515
1515
  const startPath = dirname(from);
1516
1516
  return resolve(this.extractPath, startPath, href);
1517
1517
  }
1518
+ async readFileContents(href, relativeTo, encoding) {
1519
+ const rootfile = await this.getRootfile();
1520
+ const from = relativeTo ? this.resolveHref(rootfile, relativeTo) : rootfile;
1521
+ const path = this.resolveHref(from, href);
1522
+ const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
1523
+ return itemEntry;
1524
+ }
1518
1525
  async readItemContents(id, encoding) {
1519
1526
  const rootfile = await this.getRootfile();
1520
1527
  const manifest = await this.getManifest();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@storyteller-platform/epub",
3
- "version": "0.4.6",
3
+ "version": "0.4.7",
4
4
  "type": "module",
5
5
  "module": "dist/index.js",
6
6
  "types": "dist/index.d.ts",