@spyglassmc/core 0.1.2 → 0.2.0

package/README.md

@@ -8,3 +8,10 @@
 [![Gitmoji](https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square)](https://gitmoji.carloscuesta.me/)
 
 This package is the core of the Spyglass Project. It defines the structure of a parser or validator, and provides the `SpyglassCore` class to help manage those things.
+
+## Exports
+
+* `@spyglassmc/core`: Contains all core functionalities.
+* `@spyglassmc/core/lib/browser.js`: Contains browser-specific features.
+* `@spyglassmc/core/lib/nodejs.js`: Contains Node.js-specific features.
+* `@spyglassmc/core/test-out/utils.js`: For internal development use only. Does not exist in the package published to npm.

package/lib/browser.d.ts

@@ -0,0 +1,2 @@
+export * from './common/externals/BrowserExternals.js';
+//# sourceMappingURL=browser.d.ts.map

package/lib/browser.js

@@ -0,0 +1,2 @@
+export * from './common/externals/BrowserExternals.js';
+//# sourceMappingURL=browser.js.map

package/lib/common/TwoWayMap.js

@@ -1,12 +1,7 @@
-"use strict";
-var _a;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TwoWayMap = void 0;
-class TwoWayMap {
+export class TwoWayMap {
+    _map = new Map();
+    _reversedMap = new Map();
     constructor(values = []) {
-        this._map = new Map();
-        this._reversedMap = new Map();
-        this[_a] = 'TwoWayMap';
         for (const [k, v] of values) {
             this._map.set(k, v);
             this._reversedMap.set(v, k);
@@ -69,7 +64,6 @@ class TwoWayMap {
     [Symbol.iterator]() {
         return this._map.entries();
     }
+    [Symbol.toStringTag] = 'TwoWayMap';
 }
-exports.TwoWayMap = TwoWayMap;
-_a = Symbol.toStringTag;
 //# sourceMappingURL=TwoWayMap.js.map

package/lib/common/externals/BrowserExternals.d.ts

@@ -0,0 +1,3 @@
+import type { Externals } from './index.js';
+export declare const BrowserExternals: Externals;
+//# sourceMappingURL=BrowserExternals.d.ts.map

package/lib/common/externals/BrowserExternals.js

@@ -0,0 +1,191 @@
+import { decode as arrayBufferFromBase64, encode as arrayBufferToBase64 } from 'base64-arraybuffer';
+import pako from 'pako';
+import { fileUtil } from '../../service/fileUtil.js';
+import { Uri } from '../index.js';
+class BrowserEventEmitter {
+    #listeners = new Map();
+    emit(eventName, ...args) {
+        const listeners = this.#listeners.get(eventName);
+        if (!listeners?.all?.size) {
+            return false;
+        }
+        for (const listener of listeners.all) {
+            listener(...args);
+            if (listeners.once.has(listener)) {
+                listeners.all.delete(listener);
+                listeners.once.delete(listener);
+            }
+        }
+        return false;
+    }
+    on(eventName, listener) {
+        if (!this.#listeners.has(eventName)) {
+            this.#listeners.set(eventName, { all: new Set(), once: new Set() });
+        }
+        const listeners = this.#listeners.get(eventName);
+        listeners.all.add(listener);
+        return this;
+    }
+    once(eventName, listener) {
+        if (!this.#listeners.has(eventName)) {
+            this.#listeners.set(eventName, { all: new Set(), once: new Set() });
+        }
+        const listeners = this.#listeners.get(eventName);
+        listeners.all.add(listener);
+        listeners.once.add(listener);
+        return this;
+    }
+}
+class BrowserExternalDownloader {
+    async get(uri, options = {}) {
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(options?.headers ?? {})) {
+            const values = typeof value === 'string' ? [value] : value;
+            for (const v of values) {
+                headers.append(name, v);
+            }
+        }
+        const res = await fetch(uri, {
+            headers,
+            redirect: 'follow',
+        });
+        if (!res.ok) {
+            throw new Error(`Status code ${res.status}: ${res.ok}`);
+        }
+        else {
+            return new Uint8Array(await res.arrayBuffer());
+        }
+    }
+}
+class BrowserFsWatcher {
+    on(event, listener) {
+        if (event === 'ready') {
+            listener();
+        }
+        return this;
+    }
+    once(event, listener) {
+        if (event === 'ready') {
+            listener();
+        }
+        return this;
+    }
+    async close() {
+    }
+}
+class BrowserFileSystem {
+    static LocalStorageKey = 'spyglassmc-browser-fs';
+    states;
+    constructor() {
+        this.states = JSON.parse(localStorage.getItem(BrowserFileSystem.LocalStorageKey) ?? '{}');
+    }
+    saveStates() {
+        localStorage.setItem(BrowserFileSystem.LocalStorageKey, JSON.stringify(this.states));
+    }
+    async chmod(_location, _mode) {
+        return;
+    }
+    async getAllFiles(_location) {
+        return [];
+    }
+    async mkdir(location, _options) {
+        location = fileUtil.ensureEndingSlash(location.toString());
+        if (this.states[location]) {
+            throw new Error(`EEXIST: ${location}`);
+        }
+        this.states[location] = { type: 'directory' };
+        this.saveStates();
+    }
+    async readFile(location) {
+        location = location.toString();
+        const entry = this.states[location];
+        if (!entry) {
+            throw new Error(`ENOENT: ${location}`);
+        }
+        else if (entry.type === 'directory') {
+            throw new Error(`EISDIR: ${location}`);
+        }
+        return new Uint8Array(arrayBufferFromBase64(entry.content));
+    }
+    async showFile(_path) {
+        throw new Error('showFile not supported on browser');
+    }
+    async stat(location) {
+        location = location.toString();
+        const entry = this.states[location];
+        if (!entry) {
+            throw new Error(`ENOENT: ${location}`);
+        }
+        return {
+            isDirectory: () => entry.type === 'directory',
+            isFile: () => entry.type === 'file',
+        };
+    }
+    async unlink(location) {
+        location = location.toString();
+        const entry = this.states[location];
+        if (!entry) {
+            throw new Error(`ENOENT: ${location}`);
+        }
+        delete this.states[location];
+        this.saveStates();
+    }
+    watch(_location) {
+        return new BrowserFsWatcher();
+    }
+    async writeFile(location, data, _options) {
+        location = location.toString();
+        if (typeof data === 'string') {
+            data = new TextEncoder().encode(data);
+        }
+        data = arrayBufferToBase64(data);
+        this.states[location] = { type: 'file', content: data };
+        this.saveStates();
+    }
+}
+export const BrowserExternals = {
+    archive: {
+        decompressBall(_buffer, _options) {
+            throw new Error('decompressBall not supported on browser.');
+        },
+        async gunzip(buffer) {
+            return pako.inflate(buffer);
+        },
+        async gzip(buffer) {
+            return pako.gzip(buffer);
+        },
+    },
+    crypto: {
+        async getSha1(data) {
+            if (typeof data === 'string') {
+                data = new TextEncoder().encode(data);
+            }
+            const hash = await crypto.subtle.digest('SHA-1', data);
+            return uint8ArrayToHex(new Uint8Array(hash));
+        },
+    },
+    downloader: new BrowserExternalDownloader(),
+    error: {
+        isKind(e, kind) {
+            return e instanceof Error && e.message.startsWith(kind);
+        },
+    },
+    event: {
+        EventEmitter: BrowserEventEmitter,
+    },
+    fs: new BrowserFileSystem(),
+    uri: {
+        normalize(uri) {
+            return new Uri(uri).toString();
+        },
+    },
+};
+function uint8ArrayToHex(array) {
+    let ans = '';
+    for (const v of array) {
+        ans += v.toString(16).padStart(2, '0');
+    }
+    return ans;
+}
+Object.freeze(BrowserExternals);
+//# sourceMappingURL=BrowserExternals.js.map

package/lib/common/externals/NodeJsExternals.d.ts

@@ -0,0 +1,3 @@
+import type { Externals } from './index.js';
+export declare const NodeJsExternals: Externals;
+//# sourceMappingURL=NodeJsExternals.d.ts.map

package/lib/common/externals/NodeJsExternals.js

@@ -0,0 +1,151 @@
+import chokidar from 'chokidar';
+import decompress from 'decompress';
+import followRedirects from 'follow-redirects';
+import globby from 'globby';
+import { Buffer } from 'node:buffer';
+import cp from 'node:child_process';
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { promises as fsp } from 'node:fs';
+import process from 'node:process';
+import url from 'node:url';
+import { promisify } from 'node:util';
+import zlib from 'node:zlib';
+import { promisifyAsyncIterable, Uri } from '../util.js';
+const { http, https } = followRedirects;
+const gunzip = promisify(zlib.gunzip);
+const gzip = promisify(zlib.gzip);
+class NodeJsExternalDownloader {
+    get(uri, options = {}) {
+        const protocol = new Uri(uri).protocol;
+        return new Promise((resolve, reject) => {
+            const backend = protocol === 'http:' ? http : https;
+            backend.get(uri, options, (res) => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`Status code ${res.statusCode}: ${res.statusMessage}`));
+                }
+                else {
+                    resolve(promisifyAsyncIterable(res, chunks => Buffer.concat(chunks)));
+                }
+            });
+        });
+    }
+}
+export const NodeJsExternals = {
+    archive: {
+        decompressBall(buffer, options) {
+            if (buffer instanceof Buffer) {
+                return decompress(buffer, { strip: options?.stripLevel });
+            }
+            throw new TypeError(`The 'buffer' argument for 'decompressBall' on Node.js must be an instance of 'Buffer'. Got '${buffer}' instead.`);
+        },
+        gunzip(buffer) {
+            return gunzip(buffer);
+        },
+        gzip(buffer) {
+            return gzip(buffer);
+        },
+    },
+    crypto: {
+        async getSha1(data) {
+            const hash = crypto.createHash('sha1');
+            hash.update(data);
+            return hash.digest('hex');
+        },
+    },
+    downloader: new NodeJsExternalDownloader(),
+    error: {
+        isKind(e, kind) {
+            return e instanceof Error && e.code === kind;
+        },
+    },
+    event: {
+        EventEmitter,
+    },
+    fs: {
+        chmod(location, mode) {
+            return fsp.chmod(toFsPathLike(location), mode);
+        },
+        async getAllFiles(location) {
+            return (await globby(toPath(location) + '**/*', { absolute: true, dot: true })).map(uriFromPath);
+        },
+        async mkdir(location, options) {
+            return void await fsp.mkdir(toFsPathLike(location), options);
+        },
+        readFile(location) {
+            return fsp.readFile(toFsPathLike(location));
+        },
+        async showFile(location) {
+            const execFile = promisify(cp.execFile);
+            let command;
+            switch (process.platform) {
+                case 'darwin':
+                    command = 'open';
+                    break;
+                case 'win32':
+                    command = 'explorer';
+                    break;
+                default:
+                    command = 'xdg-open';
+                    break;
+            }
+            return void await execFile(command, [toPath(location)]);
+        },
+        stat(location) {
+            return fsp.stat(toFsPathLike(location));
+        },
+        unlink(location) {
+            return fsp.unlink(toFsPathLike(location));
+        },
+        watch(location) {
+            return new ChokidarWatcherWrapper(chokidar.watch(toPath(location)));
+        },
+        writeFile(location, data, options) {
+            return fsp.writeFile(toFsPathLike(location), data, options);
+        },
+    },
+    uri: {
+        normalize(uri) {
+            if (uri.startsWith('file:')) {
+                return url.pathToFileURL(url.fileURLToPath(uri)).toString();
+            }
+            else {
+                return new Uri(uri).toString();
+            }
+        },
+    },
+};
+Object.freeze(NodeJsExternals);
+/**
+ * @returns A {@link fs.PathLike}.
+ */
+function toFsPathLike(path) {
+    if (typeof path === 'string' && path.startsWith('file:')) {
+        return new Uri(path);
+    }
+    return path;
+}
+function toPath(path) {
+    if (typeof path === 'string' && !path.startsWith('file:')) {
+        return path;
+    }
+    return uriToPath(path);
+}
+const uriToPath = (uri) => url.fileURLToPath(uri);
+const uriFromPath = (path) => url.pathToFileURL(path).toString();
+class ChokidarWatcherWrapper extends EventEmitter {
+    #watcher;
+    constructor(watcher) {
+        super();
+        this.#watcher = watcher
+            .on('ready', () => this.emit('ready'))
+            .on('add', path => this.emit('add', uriFromPath(path)))
+            .on('change', path => this.emit('change', uriFromPath(path)))
+            .on('unlink', path => this.emit('unlink', uriFromPath(path)))
+            .on('error', e => this.emit('error', e));
+    }
+    close() {
+        return this.#watcher.close();
+    }
+}
+//# sourceMappingURL=NodeJsExternals.js.map

package/lib/common/externals/downloader.d.ts

@@ -0,0 +1,31 @@
+declare type RemoteUriProtocol = 'http:' | 'https:';
+export declare type RemoteUriString = `${RemoteUriProtocol}${string}`;
+export declare const RemoteUriString: Readonly<{
+    is(value: string): value is `http:${string}` | `https:${string}`;
+}>;
+export interface ExternalDownloaderOptions {
+    /**
+     * Use an string array to set multiple values to the header.
+     */
+    headers?: Record<string, string | string[]>;
+    timeout?: number;
+}
+export interface ExternalDownloader {
+    /**
+     * @throws
+     */
+    get(uri: RemoteUriString, options?: ExternalDownloaderOptions): Promise<Uint8Array>;
+}
+export declare const ExternalDownloader: Readonly<{
+    mock(options: ExternalDownloaderMockOptions): ExternalDownloader;
+}>;
+interface ExternalDownloaderMockOptions {
+    /**
+     * A record from URIs to fixture data. The {@link ExternalDownloader.get} only returns a {@link Uint8Array},
+     * therefore `string` fixtures will be turned into a `Uint8Array` and `object` fixtures will be transformed
+     * into JSON and then turned into a `Uint8Array`.
+     */
+    fixtures: Record<RemoteUriString, string | Uint8Array | object>;
+}
+export {};
+//# sourceMappingURL=downloader.d.ts.map

package/lib/common/externals/downloader.js

@@ -0,0 +1,32 @@
+export const RemoteUriString = Object.freeze({
+    is(value) {
+        return value.startsWith('http:') || value.startsWith('https:');
+    },
+});
+export const ExternalDownloader = Object.freeze({
+    mock(options) {
+        return new ExternalDownloaderMock(options);
+    },
+});
+class ExternalDownloaderMock {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async get(uri) {
+        if (!this.options.fixtures[uri]) {
+            throw new Error(`404 not found: ${uri}`);
+        }
+        const fixture = this.options.fixtures[uri];
+        if (fixture instanceof Uint8Array) {
+            return fixture;
+        }
+        else if (typeof fixture === 'string') {
+            return new TextEncoder().encode(fixture);
+        }
+        else {
+            return new TextEncoder().encode(JSON.stringify(fixture));
+        }
+    }
+}
+//# sourceMappingURL=downloader.js.map

package/lib/common/externals/index.d.ts

@@ -0,0 +1,96 @@
+import type { Uri } from '../util.js';
+import type { ExternalDownloader } from './downloader.js';
+export * from './downloader.js';
+export interface Externals {
+    archive: {
+        decompressBall: (buffer: Uint8Array, options?: {
+            stripLevel?: number;
+        }) => Promise<DecompressedFile[]>;
+        gzip: (buffer: Uint8Array) => Promise<Uint8Array>;
+        gunzip: (buffer: Uint8Array) => Promise<Uint8Array>;
+    };
+    crypto: {
+        /**
+         * @returns SHA-1 digest of the given data in hexadecimal format.
+         */
+        getSha1: (data: string | Uint8Array) => Promise<string>;
+    };
+    downloader: ExternalDownloader;
+    error: {
+        isKind: (e: unknown, kind: ExternalErrorKind) => boolean;
+    };
+    event: {
+        EventEmitter: new () => ExternalEventEmitter;
+    };
+    fs: ExternalFileSystem;
+    uri: {
+        normalize: (uri: string) => string;
+    };
+}
+export interface DecompressedFile {
+    data: Uint8Array;
+    mode: number;
+    mtime: string;
+    path: string;
+    type: string;
+}
+export declare type ExternalErrorKind = 'EEXIST' | 'EISDIR' | 'ENOENT';
+export interface ExternalEventEmitter {
+    emit(eventName: string, ...args: unknown[]): boolean;
+    on(eventName: string, listener: (...args: unknown[]) => unknown): this;
+    once(eventName: string, listener: (...args: unknown[]) => unknown): this;
+}
+export interface ExternalFileSystem {
+    /**
+     * @param mode File mode bit mask (e.g. `0o775`).
+     */
+    chmod(location: FsLocation, mode: number): Promise<void>;
+    /**
+     * @returns an array of file URIs under the given `location`.
+     */
+    getAllFiles(location: FsLocation): Promise<string[]>;
+    /**
+     * @param options `mode` - File mode bit mask (e.g. `0o775`).
+     */
+    mkdir(location: FsLocation, options?: {
+        mode?: number;
+        recursive?: boolean;
+    }): Promise<void>;
+    readFile(location: FsLocation): Promise<Uint8Array>;
+    /**
+     * Show the file/directory in the platform-specific explorer program.
+     *
+     * Should not be called with unsanitized user-input path due to the possibility of arbitrary code execution.
+     */
+    showFile(path: FsLocation): Promise<void>;
+    stat(location: FsLocation): Promise<{
+        isDirectory(): boolean;
+        isFile(): boolean;
+    }>;
+    unlink(location: FsLocation): Promise<void>;
+    watch(location: FsLocation): FsWatcher;
+    /**
+     * @param options `mode` - File mode bit mask (e.g. `0o775`).
+     */
+    writeFile(location: FsLocation, data: string | Uint8Array, options?: {
+        mode: number;
+    }): Promise<void>;
+}
+/**
+ * A file file URI string or a URI object.
+ */
+export declare type FsLocation = string | Uri;
+export interface FsWatcher {
+    on(eventName: 'ready', listener: () => unknown): this;
+    once(eventName: 'ready', listener: () => unknown): this;
+    on(eventName: 'add', listener: (uri: string) => unknown): this;
+    once(eventName: 'add', listener: (uri: string) => unknown): this;
+    on(eventName: 'change', listener: (uri: string) => unknown): this;
+    once(eventName: 'change', listener: (uri: string) => unknown): this;
+    on(eventName: 'unlink', listener: (uri: string) => unknown): this;
+    once(eventName: 'unlink', listener: (uri: string) => unknown): this;
+    on(eventName: 'error', listener: (error: Error) => unknown): this;
+    once(eventName: 'error', listener: (error: Error) => unknown): this;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/common/externals/index.js

@@ -0,0 +1,2 @@
+export * from './downloader.js';
+//# sourceMappingURL=index.js.map

package/lib/common/index.d.ts

@@ -1,2 +1,3 @@
-export * from './util';
+export * from './externals/index.js';
+export * from './util.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/common/index.js

@@ -1,18 +1,3 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./util"), exports);
+export * from './externals/index.js';
+export * from './util.js';
 //# sourceMappingURL=index.js.map

package/lib/common/util.d.ts

@@ -1,7 +1,17 @@
-/// <reference types="node" />
 import externalBinarySearch from 'binary-search';
-import type { ProcessorContext } from '../service';
-export { URL as Uri } from 'url';
+import type { ProcessorContext } from '../service/index.js';
+import type { Externals } from './externals/index.js';
+export declare const Uri: {
+    new (url: string | URL, base?: string | URL | undefined): URL;
+    prototype: URL;
+    createObjectURL(obj: Blob | MediaSource): string;
+    revokeObjectURL(url: string): void;
+};
+export declare type Uri = URL;
+/**
+ * `NodeJS.Timeout` on Node.js and `number` on browser.
+ */
+export declare type IntervalId = any;
 /**
  * @param getCacheKey A function that takes the actual arguments being passed into the decorated method, and returns anything.
  * The result of this function will be used as the key to cache the `Promise`. By default the first element in the argument
@@ -50,15 +60,7 @@ export declare namespace ResourceLocation {
  * @returns The string value decoded from the buffer according to UTF-8.
  * Byte order mark is correctly removed.
  */
-export declare function bufferToString(buffer: Buffer): string;
-export declare function stringToBase64(str: string): string;
-export declare function base64ToString(base64: string): string;
-/**
- * @throws
- */
-export declare function getSha1(data: string | Buffer): string;
-export declare function isErrorCode(e: unknown, code: string): boolean;
-export declare function isEnoent(e: unknown): boolean;
+export declare function bufferToString(buffer: Uint8Array): string;
 export declare type Arrayable<T> = T | readonly T[];
 export declare namespace Arrayable {
     function is<T>(value: unknown, isT: (value: unknown) => value is T): value is Arrayable<T>;
@@ -68,9 +70,7 @@ export declare namespace TypePredicates {
     function isString(value: unknown): value is string;
 }
 export declare function promisifyAsyncIterable<T, U>(iterable: AsyncIterable<T>, joiner: (chunks: T[]) => U): Promise<U>;
-export declare const unzip: (buffer: Buffer) => Promise<Buffer>;
-export declare const zip: (buffer: Buffer) => Promise<Buffer>;
-export declare function parseGzippedJson<T>(buffer: Buffer): Promise<T>;
+export declare function parseGzippedJson(externals: Externals, buffer: Uint8Array): Promise<unknown>;
 export declare function isObject(value: unknown): value is Exclude<object, Array<any>>;
 export declare function merge<T extends Record<string, any>>(a: T, b: Record<string, any>): T;
 export declare type Lazy<T> = T | Lazy.ComplexLazy<T>;