@spyglassmc/core 0.1.2 → 0.4.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/Dev.d.ts

@@ -0,0 +1,11 @@
+export declare const Dev: Readonly<{
+    assertDefined<T>(value: T): asserts value is Exclude<T, undefined>;
+    assertNever(value: never): never;
+    assertTrue(value: boolean, message: string): void;
+    /**
+     * @returns An estimate of the memory taken by the given value, assuming objects are stored as array-like structures instead of dictionaries in the V8 engine.
+     */
+    estimateMemoryUsage(value: unknown): number;
+    stringify(value: unknown): string;
+}>;
+//# sourceMappingURL=Dev.d.ts.map

package/lib/common/Dev.js

@@ -0,0 +1,90 @@
+export const Dev = Object.freeze({
+    assertDefined(value) {
+        if (value === undefined) {
+            throw new Error(`'${Dev.stringify(value)}' is 'undefined'`);
+        }
+    },
+    assertNever(value) {
+        throw new Error(`'${Dev.stringify(value)}' is not of type 'never'`);
+    },
+    assertTrue(value, message) {
+        if (!value) {
+            throw new Error(`Assertion failed: ${message}. '${Dev.stringify(value)}' should be true.`);
+        }
+    },
+    /**
+     * @returns An estimate of the memory taken by the given value, assuming objects are stored as array-like structures instead of dictionaries in the V8 engine.
+     */
+    estimateMemoryUsage(value) {
+        const ByteToBits = 8;
+        const PointerSize = 8;
+        let ans = 0;
+        const calculatedObjects = new Set();
+        const stack = [value];
+        while (stack.length) {
+            const current = stack.pop();
+            switch (typeof current) {
+                case 'bigint': {
+                    const bits = Math.ceil(Math.log2(Number(current)));
+                    ans += (2 + Math.ceil(bits / (ByteToBits * PointerSize))) * PointerSize; // https://stackoverflow.com/a/54298760
+                    break;
+                }
+                case 'boolean':
+                    ans += PointerSize; // Aggressive alignment estimation.
+                    break;
+                case 'number':
+                    ans += 8;
+                    break;
+                case 'object':
+                    ans += PointerSize; // Reference pointer.
+                    if (!current || calculatedObjects.has(current)) {
+                        break;
+                    }
+                    ans += PointerSize; // Header pointer.
+                    for (const value of Object.values(current)) {
+                        stack.push(value);
+                        ans += PointerSize; // Aggressive padding estimation.
+                    }
+                    calculatedObjects.add(current);
+                    break;
+                case 'string':
+                    ans += current.length * 2;
+                    break;
+                case 'symbol':
+                    ans += PointerSize;
+                    break;
+                default:
+                    break;
+            }
+        }
+        return ans;
+    },
+    stringify(value) {
+        if (value && typeof value === 'object') {
+            try {
+                const seen = new Set();
+                return JSON.stringify(value, (_k, v) => {
+                    if (v && typeof v === 'object') {
+                        return seen.has(v) ? '[Circular]' : (seen.add(v), v);
+                    }
+                    else {
+                        return v;
+                    }
+                });
+            }
+            catch (ignored) {
+                // Most likely "Maximum callstack size exceeded".
+                // Fall back to a shallow string representation.
+                return `{ ${Object.entries(value).map(([k, v]) => `'${k}': '${String(v)}'`).join(', ')} }`;
+            }
+        }
+        else if (typeof value === 'symbol') {
+            // JavaScript does not convert `Symbol`s to strings implicitly.
+            return String(value);
+        }
+        else {
+            return `${value}`;
+        }
+    },
+});
+//# sourceMappingURL=Dev.js.map

package/lib/{service → common}/Logger.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = void 0;
-var Logger;
+export var Logger;
 (function (Logger) {
     /* istanbul ignore next */
     /**
@@ -20,7 +17,7 @@ var Logger;
         return new NoopLogger();
     }
     Logger.noop = noop;
-})(Logger = exports.Logger || (exports.Logger = {}));
+})(Logger || (Logger = {}));
 class NoopLogger {
     error() { }
     info() { }

package/lib/common/Operations.d.ts

@@ -0,0 +1,12 @@
+export declare class Operations {
+    private readonly parent?;
+    constructor(parent?: Operations | undefined);
+    private readonly undoOps;
+    private readonly redoOps;
+    private addUndoOp;
+    private addRedoOp;
+    set<O extends object, K extends keyof O>(obj: O, key: K, value: O[K], receiver?: any): void;
+    undo(): void;
+    redo(): void;
+}
+//# sourceMappingURL=Operations.d.ts.map

package/lib/common/Operations.js

@@ -0,0 +1,33 @@
+export class Operations {
+    parent;
+    constructor(parent) {
+        this.parent = parent;
+    }
+    undoOps = [];
+    redoOps = [];
+    addUndoOp(op) {
+        this.undoOps.push(op);
+        this.parent?.addUndoOp(op);
+    }
+    addRedoOp(op) {
+        this.redoOps.push(op);
+        this.parent?.addRedoOp(op);
+    }
+    set(obj, key, value, receiver = obj) {
+        const oldValue = Reflect.get(obj, key, receiver);
+        const op = () => { Reflect.set(obj, key, value, receiver); };
+        const undoOp = () => { Reflect.set(obj, key, oldValue, receiver); };
+        this.addRedoOp(op);
+        this.addUndoOp(undoOp);
+        op();
+    }
+    undo() {
+        for (let i = this.undoOps.length - 1; i >= 0; i--) {
+            this.undoOps[i]();
+        }
+    }
+    redo() {
+        this.redoOps.forEach(op => op());
+    }
+}
+//# sourceMappingURL=Operations.js.map

package/lib/common/ReadonlyProxy.d.ts

@@ -0,0 +1,9 @@
+declare type Wrap<T> = T extends object ? DeepReadonly<T> : T;
+export declare type DeepReadonly<T extends object> = {
+    readonly [K in keyof T]: Wrap<T[K]>;
+};
+export declare const ReadonlyProxy: Readonly<{
+    create<T extends object>(obj: T): DeepReadonly<T>;
+}>;
+export {};
+//# sourceMappingURL=ReadonlyProxy.d.ts.map

package/lib/common/ReadonlyProxy.js

@@ -0,0 +1,23 @@
+import { emplaceMap, isObject } from './util.js';
+export const ReadonlyProxy = Object.freeze({
+    create(obj) {
+        return new Proxy(obj, new ReadonlyProxyHandler());
+    },
+});
+class ReadonlyProxyHandler {
+    map = new Map();
+    get(target, p, receiver) {
+        const value = Reflect.get(target, p, receiver);
+        if (p !== 'prototype' && isObject(value)) {
+            return emplaceMap(this.map, p, { insert: () => ReadonlyProxy.create(value) });
+        }
+        return value;
+    }
+    set(_target, p, _value, _receiver) {
+        throw new TypeError(`Cannot set property '${String(p)}' on a readonly proxy`);
+    }
+    deleteProperty(_target, p) {
+        throw new TypeError(`Cannot delete property '${String(p)}' on a readonly proxy`);
+    }
+}
+//# sourceMappingURL=ReadonlyProxy.js.map

package/lib/common/StateProxy.d.ts

@@ -0,0 +1,35 @@
+declare const BranchOff: unique symbol;
+declare const Is: unique symbol;
+declare const Origin: unique symbol;
+declare const Redo: unique symbol;
+declare const Undo: unique symbol;
+declare type Wrap<T> = T extends object ? StateProxy<T> : T;
+/**
+ * A proxy wrapped around an arbitrary object value.
+ * You can access and mutate the value as normal, but you also have the ability to revert all changes ever since the
+ * proxy was created using {@link StateProxy.redoChanges} and {@link StateProxy.undoChanges}.
+ *
+ * A new proxy can be branched off of an existing proxy using {@link StateProxy.branchOff} to have finer control
+ * over what changes to be reverted.
+ */
+export declare type StateProxy<T extends object> = {
+    [K in keyof T]: Wrap<T[K]>;
+} & {
+    [BranchOff]: () => StateProxy<T>;
+    [Is]: true;
+    [Origin]: T;
+    [Redo]: () => void;
+    [Undo]: () => void;
+};
+export declare const StateProxy: Readonly<{
+    branchOff<T extends object>(proxy: StateProxy<T>): StateProxy<T>;
+    create<T_1 extends object>(obj: T_1): T_1 extends StateProxy<any> ? void & {
+        _cannotCreateProxyFromProxy: never;
+    } : StateProxy<T_1>;
+    dereference<T_2 extends object>(value: T_2 | StateProxy<T_2>): T_2;
+    is(obj: any): obj is StateProxy<object>;
+    redoChanges(proxy: StateProxy<object>): void;
+    undoChanges(proxy: StateProxy<object>): void;
+}>;
+export {};
+//# sourceMappingURL=StateProxy.d.ts.map

package/lib/common/StateProxy.js

@@ -0,0 +1,69 @@
+import { emplaceMap, isObject } from '../common/index.js';
+import { Operations } from './Operations.js';
+const BranchOff = Symbol('StateBranchOff');
+const Is = Symbol('IsStateProxy');
+const Origin = Symbol('OriginState');
+const Redo = Symbol('RedoStateChanges');
+const Undo = Symbol('UndoStateChanges');
+export const StateProxy = Object.freeze({
+    branchOff(proxy) {
+        return proxy[BranchOff]();
+    },
+    create(obj) {
+        if (StateProxy.is(obj)) {
+            throw new TypeError('Cannot create a proxy over a proxy. You might want to use branchOff instead.');
+        }
+        return _createStateProxy(obj, new Operations());
+    },
+    dereference(value) {
+        return StateProxy.is(value) ? value[Origin] : value;
+    },
+    is(obj) {
+        return obj?.[Is];
+    },
+    redoChanges(proxy) {
+        proxy[Redo]();
+    },
+    undoChanges(proxy) {
+        proxy[Undo]();
+    },
+});
+class StateProxyHandler {
+    rootOps;
+    map = new Map();
+    constructor(
+    /**
+     * Shared across all handlers created for the same root state object under the same branch.
+     */
+    rootOps) {
+        this.rootOps = rootOps;
+    }
+    #branchOff(target) {
+        return _createStateProxy(target, new Operations(this.rootOps));
+    }
+    get(target, p, receiver) {
+        switch (p) {
+            case BranchOff: return () => this.#branchOff(target);
+            case Is: return true;
+            case Origin: return target;
+            case Redo: return () => this.rootOps.redo();
+            case Undo: return () => this.rootOps.undo();
+        }
+        const value = Reflect.get(target, p, receiver);
+        if (p !== 'prototype' && isObject(value)) {
+            return emplaceMap(this.map, p, { insert: () => _createStateProxy(value, this.rootOps) });
+        }
+        return value;
+    }
+    set(target, p, value, receiver) {
+        if (p === BranchOff || p === Is || p === Origin || p === Redo || p === Undo) {
+            throw new TypeError(`Cannot set ${String(p)}`);
+        }
+        this.rootOps.set(target, p, StateProxy.dereference(value), receiver);
+        return true;
+    }
+}
+function _createStateProxy(target, operations) {
+    return new Proxy(target, new StateProxyHandler(operations));
+}
+//# sourceMappingURL=StateProxy.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