@satisfactory-dev/docs.json.ts 0.6.1

package/LICENSE.md

@@ -0,0 +1,190 @@
+# Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+   Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+   stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+   that You distribute, all copyright, patent, trademark, and
+   attribution notices from the Source form of the Work,
+   excluding those notices that do not pertain to any part of
+   the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+   distribution, then any Derivative Works that You distribute must
+   include a readable copy of the attribution notices contained
+   within such NOTICE file, excluding those notices that do not
+   pertain to any part of the Derivative Works, in at least one
+   of the following places: within a NOTICE text file distributed
+   as part of the Derivative Works; within the Source form or
+   documentation, if provided along with the Derivative Works; or,
+   within a display generated by the Derivative Works, if and
+   wherever such third-party notices normally appear. The contents
+   of the NOTICE file are for informational purposes only and
+   do not modify the License. You may add Your own attribution
+   notices within Derivative Works that You distribute, alongside
+   or as an addendum to the NOTICE text from the Work, provided
+   that such additional attribution notices cannot be construed
+   as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2024 SignpostMarv
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,81 @@
+[![Coverage Status](https://coveralls.io/repos/github/satisfactory-dev/Docs.json.ts/badge.svg?branch=main)](https://coveralls.io/github/satisfactory-dev/Docs.json.ts?branch=main)
+[![Workflow Status](https://github.com/satisfactory-dev/Docs.json.ts/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/satisfactory-dev/Docs.json.ts/actions/workflows/node.js.yml?query=branch%3Amain)
+
+# Current Plan for Development:
+
+-   If [the relevant QA Site post](https://questions.satisfactorygame.com/post/65e5367dcd33105bd53f931f) gets resolved via a public announcement and/or the inclusion of a license:
+    -   generated files will be included in the repo
+    -   Docs.json _may_ be included
+    -   Docs.utf8.json _may_ be included
+-   the contents of [data-progress.md](data-progress.md) do not indicate that data generation is _valid_, only that it spits out _something_.
+
+# Using
+
+## Troubleshooting
+
+-   If `SyntaxError: Invalid or unexpected token` occurs
+    -   Clear out previous precompiled Ajv validators
+    -   Clear out the generated types folder
+-   If validation fails despite no apparent changes to the schema
+    -   Clear out previous precompiled Ajv validators as the post-processing
+        (conversion of custom types to regex, etc.) may have changed.
+
+## Requirements
+
+-   Docker
+    -   recommend vscode devcontainer support
+    -   phpstorm's devcontainer support works but doesn't seem as capable
+-   A copy of Update 8's `Docs.json` file
+
+## Instructions
+
+1. Checkout locally
+1. Load in devcontainer-supporting IDE
+    - devcontainer setup should automatically run `make install`
+    - `NODE_OPTIONS` env var may require opening a fresh terminal if you
+      receieve an error along the lines of
+      `TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"`
+1. Copy `Docs.json` to `./data/`
+1. Run `make validate`
+    - if this fails, either the `Docs.json` is wrong or the schema is out-of-date
+    - if this succeeds, run `make generate`
+
+### IDE Integration
+
+-   [Docs.json.ts.dic](Docs.json.ts.dic) can be used by JetBrains' IDEs to suppress false-positive matches in the spellchecker as a result of the contents of `Docs.json`
+    -   refer to JetBrains' own documentation for adding `.dic` files to the spell checking.
+-   `eslint` can result in the IDE slowing to a crawl if the `generated-types` folder is not excluded during development.
+
+## In a separate project
+
+1. run `npm install --save @satisfactory-dev/docs.json.ts`
+1. refer to [discover-types.ts](discover-types.ts) for how to generate the
+   types & data
+
+    - You will need to replace the usage of the `docs` helper with
+      something like the following (where `${__dirname}/data/` is the data
+      path in your new project):
+
+        ```ts
+        const __dirname = __dirname_from_meta(import.meta);
+        const ajv = new Ajv({
+        	verbose: true,
+        	code: {
+        		source: true,
+        		es5: false,
+        		esm: true,
+        		optimize: true,
+        	},
+        });
+        configure_ajv(ajv);
+
+        export const docs = new DocsTsGenerator({
+        	ajv,
+        	docs_path: `${__dirname}/data/Docs.json`,
+        	cache_path: `${__dirname}/data/`,
+        });
+        ```
+
+# License
+
+[see LICENSE.md](LICENSE.md)

package/assert/CustomAssert.d.ts

@@ -0,0 +1,2 @@
+import { ExpressionResult } from '../lib/DataDiscovery/Generator';
+export declare function value_matches_ExpressionResult(maybe: unknown, expression_result: ExpressionResult, message?: string | Error): asserts maybe is typeof expression_result.expression;

package/assert/CustomAssert.js

@@ -0,0 +1,5 @@
+import assert from 'assert';
+export function value_matches_ExpressionResult(maybe, expression_result, message) {
+    assert.deepStrictEqual(maybe, expression_result.expression, message);
+}
+//# sourceMappingURL=CustomAssert.js.map

package/lib/AjvUtilities.d.ts

@@ -0,0 +1,7 @@
+import Ajv, { SchemaObject, ValidateFunction } from 'ajv/dist/2020';
+import { NoMatchError } from './Exceptions';
+export declare class FailedToCompileSchema extends NoMatchError {
+    constructor(schema: SchemaObject, err: unknown, message?: string);
+}
+export declare function compile<T>(ajv: Ajv, schema: SchemaObject): ValidateFunction<T>;
+export declare function esmify(code: string): string;

package/lib/AjvUtilities.js

@@ -0,0 +1,59 @@
+import { NoMatchError, } from './Exceptions';
+const cache = new WeakMap();
+const duplicate_compile_check = {};
+export class FailedToCompileSchema extends NoMatchError {
+    constructor(schema, err, message = 'Failed to compile schema') {
+        super({ err, schema }, message);
+    }
+}
+export function compile(ajv, schema) {
+    try {
+        performance.mark('ajv compile start');
+        if (cache.has(schema)) {
+            const result = cache.get(schema);
+            performance.measure('ajv compile cached', 'ajv compile start');
+            return result;
+        }
+        const key = JSON.stringify(schema);
+        if (key in duplicate_compile_check) {
+            performance.measure('ajv compile duplicate', 'ajv compile start');
+            return duplicate_compile_check[key];
+        }
+        const result = ajv.compile(schema);
+        cache.set(schema, result);
+        duplicate_compile_check[key] = result;
+        performance.measure('ajv compile', 'ajv compile start');
+        return result;
+    }
+    catch (err) {
+        throw new FailedToCompileSchema(schema, err);
+    }
+}
+export function esmify(code) {
+    const replacements = {
+        'require("ajv/dist/runtime/equal").default': [
+            'fast_deep_equal',
+            `import fast_deep_equal from 'fast-deep-equal';`,
+        ],
+        'require("ajv/dist/runtime/ucs2length").default': [
+            'ucs2length.default',
+            `import ucs2length from 'ajv/dist/runtime/ucs2length';`,
+        ],
+    };
+    const import_these = [];
+    for (const entry of Object.entries(replacements)) {
+        const [look_for, [replace_with, add_to_import]] = entry;
+        if (code.includes(look_for)) {
+            code = code.replace(look_for, replace_with);
+            import_these.push(add_to_import);
+        }
+    }
+    if (import_these.length) {
+        code = code.replace(/^"use strict";/, [
+            '"use strict";',
+            ...import_these,
+        ].join(''));
+    }
+    return code;
+}
+//# sourceMappingURL=AjvUtilities.js.map

package/lib/ArrayUtilities.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Created due to annoyance over array.prototype.map()
+ *	forcing [unknown, ...unknown[]] to unknown[]
+ */
+export declare function non_empty_map<ItemInput = unknown, ItemOutput = unknown, Input extends [ItemInput, ...ItemInput[]] = [ItemInput, ...ItemInput[]], Output extends [
+    ItemOutput,
+    ...ItemOutput[]
+] = [
+    ItemOutput,
+    ...ItemOutput[]
+]>(array: Input, map: (item: ItemInput) => ItemOutput): Output;
+type NonEmpty<T> = keyof T extends never ? never : T;
+export declare function non_empty_keys<T extends {
+    [key: string]: unknown;
+} = {
+    [key: string]: unknown;
+}>(object: NonEmpty<T>): [string, ...string[]];
+export declare function require_non_empty_array<Item = unknown, NotEmpty = [Item, ...Item[]]>(maybe: Item[]): NotEmpty;
+export declare function object_keys<T extends {
+    [key: string]: unknown;
+} = {
+    [key: string]: unknown;
+}>(object: T): (keyof T)[];
+export {};

package/lib/ArrayUtilities.js

@@ -0,0 +1,21 @@
+/**
+ * Created due to annoyance over array.prototype.map()
+ *	forcing [unknown, ...unknown[]] to unknown[]
+ */
+export function non_empty_map(array, map) {
+    return array.map(map);
+}
+export function non_empty_keys(object) {
+    return Object.keys(object);
+}
+export function require_non_empty_array(maybe) {
+    if (maybe.length < 1) {
+        throw new Error('Array is empty!');
+    }
+    return maybe;
+}
+// because typescript doesn't do this automatically
+export function object_keys(object) {
+    return Object.keys(object);
+}
+//# sourceMappingURL=ArrayUtilities.js.map

package/lib/CustomParsingTypes/CustomPairingTypes.d.ts

@@ -0,0 +1,37 @@
+export declare function object_has_property<Property extends string = string, Value = unknown>(maybe: unknown, property: Property, predicate?: undefined | ((maybe: unknown) => maybe is Value)): maybe is {
+    [key: string]: unknown;
+} & {
+    [key in Property]: Value;
+};
+export declare function object_has_only_properties_that_match_predicate<Value = unknown>(maybe: unknown, predicate: (object_value: unknown) => object_value is Value): maybe is {
+    [key: string]: Value;
+};
+export declare function property_exists_on_object(object: {
+    [key: string]: unknown;
+}, property: string): property is keyof object;
+export declare function object_has_non_empty_array_property<Property extends string = string, Value = unknown>(maybe: unknown, property: Property, predicate?: undefined | ((inner_maybe: unknown) => inner_maybe is Value)): maybe is ({
+    [key: string]: unknown;
+} & {
+    [key in Property]: [Value, ...Value[]];
+});
+export declare function object_has_property_that_equals(maybe: unknown, property: string, expects: unknown): maybe is {
+    [key: string]: unknown;
+} & {
+    [key in typeof property]: typeof expects;
+};
+export declare function value_is_non_array_object(maybe: unknown): maybe is {
+    [key: string]: unknown;
+};
+export declare function is_non_empty_array<T = unknown>(maybe: unknown, predicate?: undefined | ((inner_maybe: unknown) => inner_maybe is T)): maybe is [T, ...T[]];
+export declare function object_only_has_that_property<T = unknown>(maybe: unknown, property: string, predicate?: undefined | ((maybe: unknown) => maybe is T)): maybe is {
+    [key in typeof property]: T;
+};
+export declare function annoyingly_have_to_escape_property(property: string): string;
+export declare abstract class SupportedSubSchemaType<ObjectType extends {
+    [key: string]: unknown;
+} = {
+    [key: string]: unknown;
+}> {
+    abstract is_supported_schema(maybe: unknown): maybe is ObjectType;
+    abstract value_regex(value: ObjectType): string;
+}

package/lib/CustomParsingTypes/CustomPairingTypes.js

@@ -0,0 +1,42 @@
+export function object_has_property(maybe, property, predicate = undefined) {
+    return (value_is_non_array_object(maybe)
+        && property in maybe
+        && (undefined === predicate
+            || predicate(maybe[property])));
+}
+export function object_has_only_properties_that_match_predicate(maybe, predicate) {
+    return (value_is_non_array_object(maybe)
+        && Object.values(maybe).every(e => predicate(e)));
+}
+export function property_exists_on_object(object, property) {
+    return property in object;
+}
+export function object_has_non_empty_array_property(maybe, property, predicate = undefined) {
+    return (object_has_property(maybe, property)
+        && is_non_empty_array(maybe[property], predicate));
+}
+export function object_has_property_that_equals(maybe, property, expects) {
+    return object_has_property(maybe, property) && expects === maybe[property];
+}
+export function value_is_non_array_object(maybe) {
+    return ('object' === typeof maybe
+        && !(maybe instanceof Array)
+        && null !== maybe);
+}
+export function is_non_empty_array(maybe, predicate = undefined) {
+    return (maybe instanceof Array
+        && maybe.length >= 1
+        && (undefined === predicate || maybe.every((e) => predicate(e))));
+}
+export function object_only_has_that_property(maybe, property, predicate = undefined) {
+    return (value_is_non_array_object(maybe)
+        && object_has_property(maybe, property)
+        && 1 === Object.keys(maybe).length
+        && (undefined === predicate || predicate(maybe[property])));
+}
+export function annoyingly_have_to_escape_property(property) {
+    return property.replace(/([[\]])/g, '\\$1');
+}
+export class SupportedSubSchemaType {
+}
+//# sourceMappingURL=CustomPairingTypes.js.map