@likecoin/epub-ts 0.3.93

package/README.md

@@ -0,0 +1,64 @@
+# epub.ts (`@likecoin/epub-ts`)
+
+A TypeScript fork of [epubjs](https://github.com/futurepress/epub.js) v0.3.93 by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress) — parse and render EPUB documents in the browser.
+
+This library is primarily developed for internal use at [3ook.com](https://3ook.com) and is provided as-is. It was mainly built with AI-assisted development.
+
+## Install
+
+```bash
+npm install @likecoin/epub-ts
+```
+
+## Quick Start
+
+```js
+import ePub from "@likecoin/epub-ts";
+
+// Same API as epubjs
+const book = ePub("/path/to/book.epub");
+const rendition = book.renderTo("viewer", { width: 600, height: 400 });
+rendition.display();
+```
+
+## Migration from epubjs
+
+This is a drop-in replacement. Change your import:
+
+```diff
+- import ePub from "epubjs";
++ import ePub from "@likecoin/epub-ts";
+```
+
+All APIs remain the same.
+
+## Named Exports
+
+```js
+import { Book, EpubCFI, Rendition, Contents, Layout } from "@likecoin/epub-ts";
+```
+
+## What's Changed
+
+- Build: webpack + Babel → Vite
+- Tests: Karma + Mocha → Vitest
+- Source: JavaScript → TypeScript (incremental conversion)
+- Removed dependencies: `core-js`, `lodash`, `path-webpack`
+- Replaced `event-emitter` with inline typed emitter
+
+## Development
+
+```bash
+npm install
+npm run build     # Vite library build → dist/
+npm test          # Vitest
+npm run typecheck # tsc --noEmit
+```
+
+## Contributing
+
+See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for current conversion progress and what to work on.
+
+## License
+
+BSD-2-Clause (same as epubjs)

package/dist/annotations.d.ts

@@ -0,0 +1,159 @@
+import { IEventEmitter } from './types';
+import { default as Rendition } from './rendition';
+interface AnnotationView {
+    index: number;
+    highlight: Function;
+    underline: Function;
+    mark: Function;
+    unhighlight: Function;
+    ununderline: Function;
+    unmark: Function;
+}
+/**
+    * Handles managing adding & removing Annotations
+    * @param {Rendition} rendition
+    * @class
+    */
+declare class Annotations {
+    rendition: Rendition;
+    highlights: Annotation[];
+    underlines: Annotation[];
+    marks: Annotation[];
+    _annotations: Record<string, Annotation>;
+    _annotationsBySectionIndex: Record<number, string[]>;
+    constructor(rendition: Rendition);
+    /**
+     * Add an annotation to store
+     * @param {string} type Type of annotation to add: "highlight", "underline", "mark"
+     * @param {EpubCFI} cfiRange EpubCFI range to attach annotation to
+     * @param {object} data Data to assign to annotation
+     * @param {function} [cb] Callback after annotation is added
+     * @param {string} className CSS class to assign to annotation
+     * @param {object} styles CSS styles to assign to annotation
+     * @returns {Annotation} annotation
+     */
+    add(type: string, cfiRange: string, data?: Record<string, any>, cb?: Function, className?: string, styles?: Record<string, string>): Annotation;
+    /**
+     * Remove an annotation from store
+     * @param {EpubCFI} cfiRange EpubCFI range the annotation is attached to
+     * @param {string} type Type of annotation to add: "highlight", "underline", "mark"
+     */
+    remove(cfiRange: string, type?: string): void;
+    /**
+     * Remove an annotations by Section Index
+     * @private
+     */
+    _removeFromAnnotationBySectionIndex(sectionIndex: number, hash: string): void;
+    /**
+     * Get annotations by Section Index
+     * @private
+     */
+    _annotationsAt(index: number): string[];
+    /**
+     * Add a highlight to the store
+     * @param {EpubCFI} cfiRange EpubCFI range to attach annotation to
+     * @param {object} data Data to assign to annotation
+     * @param {function} cb Callback after annotation is clicked
+     * @param {string} className CSS class to assign to annotation
+     * @param {object} styles CSS styles to assign to annotation
+     */
+    highlight(cfiRange: string, data?: Record<string, any>, cb?: Function, className?: string, styles?: Record<string, string>): Annotation;
+    /**
+     * Add a underline to the store
+     * @param {EpubCFI} cfiRange EpubCFI range to attach annotation to
+     * @param {object} data Data to assign to annotation
+     * @param {function} cb Callback after annotation is clicked
+     * @param {string} className CSS class to assign to annotation
+     * @param {object} styles CSS styles to assign to annotation
+     */
+    underline(cfiRange: string, data?: Record<string, any>, cb?: Function, className?: string, styles?: Record<string, string>): Annotation;
+    /**
+     * Add a mark to the store
+     * @param {EpubCFI} cfiRange EpubCFI range to attach annotation to
+     * @param {object} data Data to assign to annotation
+     * @param {function} cb Callback after annotation is clicked
+     */
+    mark(cfiRange: string, data?: Record<string, any>, cb?: Function): Annotation;
+    /**
+     * iterate over annotations in the store
+     */
+    each(..._args: any[]): any;
+    /**
+     * Hook for injecting annotation into a view
+     * @param {View} view
+     * @private
+     */
+    inject(view: AnnotationView): void;
+    /**
+     * Hook for removing annotation from a view
+     * @param {View} view
+     * @private
+     */
+    clear(view: AnnotationView): void;
+    /**
+     * [Not Implemented] Show annotations
+     * @TODO: needs implementation in View
+     */
+    show(): void;
+    /**
+     * [Not Implemented] Hide annotations
+     * @TODO: needs implementation in View
+     */
+    hide(): void;
+}
+/**
+ * Annotation object
+ * @class
+ * @param {object} options
+ * @param {string} options.type Type of annotation to add: "highlight", "underline", "mark"
+ * @param {EpubCFI} options.cfiRange EpubCFI range to attach annotation to
+ * @param {object} options.data Data to assign to annotation
+ * @param {int} options.sectionIndex Index in the Spine of the Section annotation belongs to
+ * @param {function} [options.cb] Callback after annotation is clicked
+ * @param {string} className CSS class to assign to annotation
+ * @param {object} styles CSS styles to assign to annotation
+ * @returns {Annotation} annotation
+ */
+declare class Annotation implements IEventEmitter {
+    type: string;
+    cfiRange: string;
+    data: Record<string, any>;
+    sectionIndex: number;
+    mark: object | undefined;
+    cb: Function;
+    className: string;
+    styles: Record<string, string>;
+    on: IEventEmitter["on"];
+    off: IEventEmitter["off"];
+    emit: IEventEmitter["emit"];
+    constructor({ type, cfiRange, data, sectionIndex, cb, className, styles }: {
+        type: string;
+        cfiRange: string;
+        data?: Record<string, any>;
+        sectionIndex?: number;
+        cb?: Function;
+        className?: string;
+        styles?: Record<string, string>;
+    });
+    /**
+     * Update stored data
+     * @param {object} data
+     */
+    update(data: Record<string, any>): void;
+    /**
+     * Add to a view
+     * @param {View} view
+     */
+    attach(view: AnnotationView): object | undefined;
+    /**
+     * Remove from a view
+     * @param {View} view
+     */
+    detach(view: AnnotationView): object | undefined;
+    /**
+     * [Not Implemented] Get text of an annotation
+     * @TODO: needs implementation in contents
+     */
+    text(): void;
+}
+export default Annotations;

package/dist/archive.d.ts

@@ -0,0 +1,82 @@
+import { default as JSZip } from 'jszip';
+/**
+ * Handles Unzipping a requesting files from an Epub Archive
+ * @class
+ */
+declare class Archive {
+    zip: JSZip;
+    urlCache: Record<string, string>;
+    constructor();
+    /**
+     * Checks to see if JSZip exists in global namspace,
+     * Requires JSZip if it isn't there
+     * @private
+     */
+    checkRequirements(): void;
+    /**
+     * Open an archive
+     * @param  {binary} input
+     * @param  {boolean} [isBase64] tells JSZip if the input data is base64 encoded
+     * @return {Promise} zipfile
+     */
+    open(input: ArrayBuffer | string | Blob, isBase64?: boolean): Promise<JSZip>;
+    /**
+     * Load and Open an archive
+     * @param  {string} zipUrl
+     * @param  {boolean} [isBase64] tells JSZip if the input data is base64 encoded
+     * @return {Promise} zipfile
+     */
+    openUrl(zipUrl: string, isBase64?: boolean): Promise<JSZip>;
+    /**
+     * Request a url from the archive
+     * @param  {string} url  a url to request from the archive
+     * @param  {string} [type] specify the type of the returned result
+     * @return {Promise<Blob | string | JSON | Document | XMLDocument>}
+     */
+    request(url: string, type?: string): Promise<any>;
+    /**
+     * Handle the response from request
+     * @private
+     * @param  {any} response
+     * @param  {string} [type]
+     * @return {any} the parsed result
+     */
+    handleResponse(response: any, type?: string): any;
+    /**
+     * Get a Blob from Archive by Url
+     * @param  {string} url
+     * @param  {string} [mimeType]
+     * @return {Blob}
+     */
+    getBlob(url: string, mimeType?: string): Promise<Blob> | undefined;
+    /**
+     * Get Text from Archive by Url
+     * @param  {string} url
+     * @param  {string} [encoding]
+     * @return {string}
+     */
+    getText(url: string, _encoding?: string): Promise<string> | undefined;
+    /**
+     * Get a base64 encoded result from Archive by Url
+     * @param  {string} url
+     * @param  {string} [mimeType]
+     * @return {string} base64 encoded
+     */
+    getBase64(url: string, mimeType?: string): Promise<string> | undefined;
+    /**
+     * Create a Url from an unarchived item
+     * @param  {string} url
+     * @param  {object} [options.base64] use base64 encoding or blob url
+     * @return {Promise} url promise with Url string
+     */
+    createUrl(url: string, options?: {
+        base64?: boolean;
+    }): Promise<string>;
+    /**
+     * Revoke Temp Url for a archive item
+     * @param  {string} url url of the item in the archive
+     */
+    revokeUrl(url: string): void;
+    destroy(): void;
+}
+export default Archive;

package/dist/book.d.ts

@@ -0,0 +1,228 @@
+import { defer } from './utils/core';
+import { default as Url } from './utils/url';
+import { default as Path } from './utils/path';
+import { default as Spine } from './spine';
+import { default as Locations } from './locations';
+import { default as Container } from './container';
+import { default as Packaging } from './packaging';
+import { default as Navigation } from './navigation';
+import { default as Resources } from './resources';
+import { default as PageList } from './pagelist';
+import { default as Rendition } from './rendition';
+import { default as Archive } from './archive';
+import { default as Store } from './store';
+import { default as DisplayOptions } from './displayoptions';
+import { IEventEmitter, BookOptions, RenditionOptions, RequestFunction } from './types';
+import { default as Section } from './section';
+interface BookLoadingState {
+    manifest: defer;
+    spine: defer;
+    metadata: defer;
+    cover: defer;
+    navigation: defer;
+    pageList: defer;
+    resources: defer;
+    displayOptions: defer;
+}
+interface BookLoadedState {
+    manifest: Promise<any>;
+    spine: Promise<any>;
+    metadata: Promise<any>;
+    cover: Promise<any>;
+    navigation: Promise<any>;
+    pageList: Promise<any>;
+    resources: Promise<any>;
+    displayOptions: Promise<any>;
+}
+/**
+ * An Epub representation with methods for the loading, parsing and manipulation
+ * of its contents.
+ * @class
+ * @param {string} [url]
+ * @param {object} [options]
+ * @param {method} [options.requestMethod] a request function to use instead of the default
+ * @param {boolean} [options.requestCredentials=undefined] send the xhr request withCredentials
+ * @param {object} [options.requestHeaders=undefined] send the xhr request headers
+ * @param {string} [options.encoding=binary] optional to pass 'binary' or base64' for archived Epubs
+ * @param {string} [options.replacements=none] use base64, blobUrl, or none for replacing assets in archived Epubs
+ * @param {method} [options.canonical] optional function to determine canonical urls for a path
+ * @param {string} [options.openAs] optional string to determine the input type
+ * @param {string} [options.store=false] cache the contents in local storage, value should be the name of the reader
+ * @returns {Book}
+ * @example new Book("/path/to/book.epub", {})
+ * @example new Book({ replacements: "blobUrl" })
+ */
+declare class Book implements IEventEmitter {
+    settings: BookOptions & Record<string, any>;
+    opening: defer;
+    opened: Promise<Book> | undefined;
+    isOpen: boolean;
+    loading: BookLoadingState | undefined;
+    loaded: BookLoadedState | undefined;
+    ready: Promise<any[]> | undefined;
+    isRendered: boolean;
+    request: RequestFunction;
+    spine: Spine | undefined;
+    locations: Locations | undefined;
+    navigation: Navigation | undefined;
+    pageList: PageList | undefined;
+    url: Url | undefined;
+    path: Path | undefined;
+    archived: boolean;
+    archive: Archive | undefined;
+    storage: Store | undefined;
+    resources: Resources | undefined;
+    rendition: Rendition | undefined;
+    container: Container | undefined;
+    packaging: Packaging | undefined;
+    displayOptions: DisplayOptions | undefined;
+    package: Packaging | undefined;
+    cover: string;
+    on: IEventEmitter["on"];
+    off: IEventEmitter["off"];
+    emit: IEventEmitter["emit"];
+    constructor(url?: string | ArrayBuffer | Blob | BookOptions, options?: BookOptions);
+    /**
+     * Open a epub or url
+     * @param {string | ArrayBuffer} input Url, Path or ArrayBuffer
+     * @param {string} [what="binary", "base64", "epub", "opf", "json", "directory"] force opening as a certain type
+     * @returns {Promise} of when the book has been loaded
+     * @example book.open("/path/to/book.epub")
+     */
+    open(input: string | ArrayBuffer | Blob, what?: string): Promise<void>;
+    /**
+     * Open an archived epub
+     * @private
+     * @param  {binary} data
+     * @param  {string} [encoding]
+     * @return {Promise}
+     */
+    openEpub(data: string | ArrayBuffer | Blob, encoding?: string): Promise<void>;
+    /**
+     * Open the epub container
+     * @private
+     * @param  {string} url
+     * @return {string} packagePath
+     */
+    openContainer(url: string): Promise<string>;
+    /**
+     * Open the Open Packaging Format Xml
+     * @private
+     * @param  {string} url
+     * @return {Promise}
+     */
+    openPackaging(url: string): Promise<void>;
+    /**
+     * Open the manifest JSON
+     * @private
+     * @param  {string} url
+     * @return {Promise}
+     */
+    openManifest(url: string): Promise<void>;
+    /**
+     * Load a resource from the Book
+     * @param  {string} path path to the resource to load
+     * @return {Promise}     returns a promise with the requested resource
+     */
+    load(path: string, _type?: string): Promise<any>;
+    /**
+     * Resolve a path to it's absolute position in the Book
+     * @param  {string} path
+     * @param  {boolean} [absolute] force resolving the full URL
+     * @return {string}          the resolved path string
+     */
+    resolve(path: string, absolute?: boolean): string;
+    /**
+     * Get a canonical link to a path
+     * @param  {string} path
+     * @return {string} the canonical path string
+     */
+    canonical(path: string): string;
+    /**
+     * Determine the type of they input passed to open
+     * @private
+     * @param  {string} input
+     * @return {string}  binary | directory | epub | opf
+     */
+    determineType(input: string | ArrayBuffer | Blob): string;
+    /**
+     * unpack the contents of the Books packaging
+     * @private
+     * @param {Packaging} packaging object
+     */
+    unpack(packaging: Packaging): void;
+    /**
+     * Load Navigation and PageList from package
+     * @private
+     * @param {Packaging} packaging
+     */
+    loadNavigation(packaging: Packaging): Promise<Navigation>;
+    /**
+     * Gets a Section of the Book from the Spine
+     * Alias for `book.spine.get`
+     * @param {string} target
+     * @return {Section}
+     */
+    section(target: string | number): Section | null;
+    /**
+     * Sugar to render a book to an element
+     * @param  {element | string} element element or string to add a rendition to
+     * @param  {object} [options]
+     * @return {Rendition}
+     */
+    renderTo(element: HTMLElement | string, options?: RenditionOptions): Rendition;
+    /**
+     * Set if request should use withCredentials
+     * @param {boolean} credentials
+     */
+    setRequestCredentials(credentials: boolean): void;
+    /**
+     * Set headers request should use
+     * @param {object} headers
+     */
+    setRequestHeaders(headers: Record<string, string>): void;
+    /**
+     * Unarchive a zipped epub
+     * @private
+     * @param  {binary} input epub data
+     * @param  {string} [encoding]
+     * @return {Archive}
+     */
+    unarchive(input: string | ArrayBuffer | Blob, encoding?: string): Promise<any>;
+    /**
+     * Store the epubs contents
+     * @private
+     * @param  {binary} input epub data
+     * @param  {string} [encoding]
+     * @return {Store}
+     */
+    store(name: string | boolean): Store;
+    /**
+     * Get the cover url
+     * @return {Promise<?string>} coverUrl
+     */
+    coverUrl(): Promise<string | null>;
+    /**
+     * Load replacement urls
+     * @private
+     * @return {Promise} completed loading urls
+     */
+    replacements(): Promise<void>;
+    /**
+     * Find a DOM Range for a given CFI Range
+     * @param  {EpubCFI} cfiRange a epub cfi range
+     * @return {Promise}
+     */
+    getRange(cfiRange: string): Promise<Range>;
+    /**
+     * Generates the Book Key using the identifier in the manifest or other string provided
+     * @param  {string} [identifier] to use instead of metadata identifier
+     * @return {string} key
+     */
+    key(identifier?: string): string;
+    /**
+     * Destroy the Book and all associated objects
+     */
+    destroy(): void;
+}
+export default Book;

package/dist/container.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Handles Parsing and Accessing an Epub Container
+ * @class
+ * @param {document} [containerDocument] xml document
+ */
+declare class Container {
+    packagePath: string;
+    directory: string;
+    encoding: string;
+    constructor(containerDocument?: Document);
+    /**
+     * Parse the Container XML
+     * @param  {document} containerDocument
+     */
+    parse(containerDocument: Document): void;
+    destroy(): void;
+}
+export default Container;