@spyglassmc/core 0.1.1 → 0.3.0

package/lib/common/externals/NodeJsExternals.js

@@ -0,0 +1,152 @@
+// https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/60592
+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,9 @@
-export * from './util';
+export * from './Dev.js';
+export * from './externals/index.js';
+export * from './Logger.js';
+export * from './Operations.js';
+export * from './ReadonlyProxy.js';
+export * from './StateProxy.js';
+export * from './TwoWayMap.js';
+export * from './util.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/common/index.js

@@ -1,14 +1,9 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
-}) : (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 './Dev.js';
+export * from './externals/index.js';
+export * from './Logger.js';
+export * from './Operations.js';
+export * from './ReadonlyProxy.js';
+export * from './StateProxy.js';
+export * from './TwoWayMap.js';
+export * from './util.js';
 //# sourceMappingURL=index.js.map

package/lib/common/util.d.ts

@@ -1,21 +1,32 @@
-/// <reference types="node" />
 import externalBinarySearch from 'binary-search';
-import type { URL as Uri } from 'url';
-import type { ProcessorContext, RootUriString } from '../service';
-export { URL as Uri } from 'url';
+import type { AstNode } from '../node/index.js';
+import type { ProcessorContext } from '../service/index.js';
+import type { Externals } from './externals/index.js';
+import type { DeepReadonly } from './ReadonlyProxy.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;
 /**
- * @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
+ * `NodeJS.Timeout` on Node.js and `number` on browser.
+ */
+export declare type IntervalId = any;
+/**
+ * @param getKey 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 identify the `Promise`. By default the first element in the argument
  * list will be used.
  *
  * This is a decorator for async methods. Decorated methods will return the same `Promise` for
- * the same arguments, provided that the cached `Promise` is still pending.
+ * the same key, provided that the previously returned `Promise` is still pending.
  */
-export declare function CachePromise(getCacheKey?: (args: any[]) => any): MethodDecorator;
+export declare function SingletonPromise(getKey?: (args: any[]) => any): MethodDecorator;
 /**
- * This is a decorator for async methods. Decorated methods will return the same `Promise` no matter what.
+ * This is a decorator for methods. Decorated methods will return the same non-`undefined` value no matter what.
  */
-export declare const SingletonPromise: MethodDecorator;
+export declare const Singleton: MethodDecorator;
 /**
  * @param getKey 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 `Timeout`. By default the first element in the argument
@@ -24,22 +35,6 @@ export declare const SingletonPromise: MethodDecorator;
  * Decorated methods will be scheduled to run after `ms` milliseconds. The timer will reset when the method is called again.
  */
 export declare function Delay(ms: number, getKey?: (args: any[]) => any): MethodDecorator;
-export declare namespace SpyglassUri {
-    const Protocol = "spyglassmc:";
-    namespace Archive {
-        const Hostname = "archive";
-        function get(archiveUri: string): RootUriString;
-        function get(archiveUri: string, pathInArchive: string): string;
-        function is(uri: Uri): boolean;
-        /**
-         * @throws When `uri` has the wrong protocol or hostname.
-         */
-        function decode(uri: Uri): {
-            archiveUri: string;
-            pathInArchive: string;
-        };
-    }
-}
 export declare type FullResourceLocation = `${string}:${string}`;
 export interface ResourceLocation {
     isTag: boolean;
@@ -67,15 +62,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>;
@@ -85,10 +72,11 @@ 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 isObject(value: unknown): value is Exclude<object, Array<any>>;
+export declare function parseGzippedJson(externals: Externals, buffer: Uint8Array): Promise<unknown>;
+/**
+ * @returns Is Plain Old JavaScript Object (POJO).
+ */
+export declare function isPojo(value: unknown): value is Record<string, unknown>;
 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>;
 export declare namespace Lazy {
@@ -117,4 +105,27 @@ export declare namespace Lazy {
 export declare function getStates(category: 'block' | 'fluid', ids: readonly string[], ctx: ProcessorContext): Record<string, string[]>;
 export declare const binarySearch: typeof externalBinarySearch;
 export declare function isIterable(value: unknown): value is Iterable<unknown>;
+export declare function atArray<T>(array: readonly T[] | undefined, index: number): T | undefined;
+export declare function emplaceMap<K, V>(map: Map<K, V>, key: K, handler: {
+    insert?: (key: K, map: Map<K, V>) => V;
+    update?: (existing: V, key: K, map: Map<K, V>) => V;
+}): V;
+/**
+ * @returns If `val` is an non-null object or a callable object (i.e. function).
+ */
+export declare function isObject(val: unknown): val is object;
+/**
+ * @example
+ * ```ts
+ * function isCommentNode<T extends DeepReadonly<AstNode> | undefined>(node: T): node is IsHelper<AstNode, CommentNode, T>
+ * ```
+ */
+export declare type IsHelper<ROOT extends object, TARGET extends ROOT, INPUT extends DeepReadonly<ROOT> | undefined> = INPUT extends DeepReadonly<ROOT> ? INPUT & DeepReadonly<TARGET> : INPUT & TARGET;
+/**
+ * @example
+ * ```ts
+ * function isCommentNode<T extends DeepReadonly<AstNode> | undefined>(node: T): node is NodeIsHelper<CommentNode, T>
+ * ```
+ */
+export declare type NodeIsHelper<TARGET extends AstNode, INPUT extends DeepReadonly<AstNode> | undefined> = IsHelper<AstNode, TARGET, INPUT>;
 //# sourceMappingURL=util.d.ts.map