@nf2t/nifitools-js 0.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@nf2t/nifitools-js",
+  "private": false,
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/main.js",
+  "types": "./dist/main.d.ts",
+  "dependencies": {
+    "jszip": "^3.10.1",
+    "zod": "^3.22.4",
+    "@nf2t/flowfiletools-js": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.2",
+    "tsup": "^8.2.4",
+    "tsx": "^4.19.1",
+    "typescript": "^5.2.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "tsx src/tests.ts"
+  }
+}

package/src/main.ts

@@ -0,0 +1,31 @@
+
+export {
+    NarAttributeTypeSchema,
+    NarAttributeSchema,
+    NarAttributesSchema, 
+    NarExtensionRelationship ,
+    NarExtensionProperty ,
+    NarExtensionSchema,
+    NarExtensionsSchema ,
+    ManifestSchema ,
+    NarSchema,
+    NarsSchema ,
+    NarExportSchema,
+    WriteNarsSchema,
+    readNars,
+} from "./readNars";
+
+export type {
+    NarAttributeType,
+    NarAttribute,
+    NarAttributes,
+    NarExtension,
+    NarExtensions,
+    Manifest,
+    Nar,
+    Nars,
+    IncomingFiles,
+    ReadNarsParameters,
+    ReadNarsResult,
+    WriteNars,
+} from "./readNars";

package/src/readNars.ts

@@ -0,0 +1,366 @@
+import JSZip from "jszip";
+import { z } from "zod";
+
+export const NarAttributeTypeSchema = z.enum(["writes", "reads"]);
+
+export type NarAttributeType = z.infer<typeof NarAttributeTypeSchema>;
+
+export const NarAttributeSchema = z.object({
+    narId: z.string(),
+    extensionId: z.string(),
+    type: NarAttributeTypeSchema,
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+})
+
+export type NarAttribute = z.infer<typeof NarAttributeSchema>;
+export const NarAttributesSchema = z.array(NarAttributeSchema);
+export type NarAttributes = z.infer<typeof NarAttributesSchema>;
+
+export const NarExtensionRelationship = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    autoTerminated: z.boolean(),
+});
+
+export const NarExtensionProperty = z.object({
+    name: z.string(),
+    displayName: z.string(),
+    description: z.string().optional(),
+    required: z.boolean().optional(),
+    sensitive: z.boolean().optional(),
+    expressionLanguageSupported: z.boolean().optional(),
+    expressionLanguageScope: z.string().optional(),
+    dynamicallyModifiesClasspath: z.boolean().optional(),
+    dynamic: z.boolean().optional(),
+});
+
+export const NarExtensionSchema = z.object({
+    narId: z.string(),
+    name: z.string(),
+    type: z.string(),
+    description: z.string().optional(),
+    tags: z.array(z.string()),
+    relationships: z.array(NarExtensionRelationship),
+    properties: z.array(NarExtensionProperty),
+    // These might be properties of the Property
+    required: z.boolean().optional(),
+    sensitive: z.boolean().optional(),
+    expressionLanguageSupported: z.boolean().optional(),
+    expressionLanguageScope: z.string().optional(),
+    dynamicallyModifiesClasspath: z.boolean().optional(),
+    dynamic: z.boolean().optional(),
+});
+
+export type NarExtension = z.infer<typeof NarExtensionSchema>;
+export const NarExtensionsSchema = z.array(NarExtensionSchema);
+export type NarExtensions = z.infer<typeof NarExtensionsSchema>;
+
+export const ManifestSchema = z.record(z.string(), z.string());
+export type Manifest = z.infer<typeof ManifestSchema>;
+
+export const NarSchema = z.object({
+    manifest: ManifestSchema,
+    name: z.string(),
+    lastModified: z.number(),
+    size: z.number(),
+    systemApiVersion: z.string().optional(),
+    groupId: z.string().optional(),
+    artifactId: z.string().optional(),
+    version: z.string().optional(),
+    buildTag: z.string().optional(),
+    buildTimestamp: z.string().optional(),
+});
+
+export type Nar = z.infer<typeof NarSchema>;
+export const NarsSchema = z.array(NarSchema);
+export type Nars = z.infer<typeof NarsSchema>;
+
+export const NarExportSchema = z.object({
+    nars: NarsSchema,
+    extensions: NarExtensionsSchema,
+    attributes: NarAttributesSchema,
+})
+
+export type IncomingFiles = File[];
+
+export type ReadNarsParameters = {
+    //TODO: Update implementation of processNars to consume File[] rather than a FileList
+    files: IncomingFiles, 
+    options?: JSZip.JSZipLoadOptions
+
+    DOMParser: DOMParser,
+    setCurrentProgress: (current: number, total: number) => void,
+    parseNar: (nar: Nar) => Promise<void>,
+    parseExtension: (extension: NarExtension) => Promise<void>,
+    parseAttribute: (extension: NarAttribute) => Promise<void>,
+}
+
+type ReadExtensionManifestParameters = {
+    file: File, 
+    extensionManifest: Document,
+    manifest: Manifest,
+    parseNar: (nar: Nar) => Promise<void>,
+    parseExtension: (extension: NarExtension) => Promise<void>,
+    parseAttribute: (extension: NarAttribute) => Promise<void>,
+}
+
+type AttributesLuv = {
+    type: NarAttributeType,
+    selectors: string,
+}
+
+const attributesLut: AttributesLuv[] = [
+    {
+        type: "reads",
+        selectors: "readsAttributes > readsAttribute",
+    },
+    {
+        type: "writes",
+        selectors: "writesAttributes > writesAttribute",
+    },
+]
+
+function querySelectorString(element: Document | Element, selectors: string) {
+    return element.querySelector(selectors)?.textContent || undefined;
+}
+
+function querySelectorBoolean(element: Document | Element, selectors: string) {
+    const value = querySelectorString(element, selectors);
+    if(value === "true") {
+        return true;
+    }
+    else if(value === "false") {
+        return true;
+    }
+    return undefined;
+}
+
+async function readExtensionManifest({file, manifest, extensionManifest, parseNar, parseExtension, parseAttribute }: ReadExtensionManifestParameters) {
+    const rawNarInfo: Partial<Nar> = {
+        manifest: manifest,
+        name: file.name,
+        lastModified: file.lastModified,
+        size: file.size,
+        systemApiVersion: querySelectorString(extensionManifest, "systemApiVersion"),
+        groupId: querySelectorString(extensionManifest, "groupId"),
+        artifactId: querySelectorString(extensionManifest, "artifactId"),
+        version: querySelectorString(extensionManifest, "version"),
+        buildTag: querySelectorString(extensionManifest, "buildInfo > tag"),
+        buildTimestamp: querySelectorString(extensionManifest, "buildInfo > timestamp"),
+    }
+
+    const narResult = await NarSchema.safeParseAsync(rawNarInfo);
+
+    if(!narResult.success) {
+        console.error({
+            file: file.name,
+            type: "Unable to parse NarSchema",
+            error: narResult.error,
+        });
+        return;
+    }
+
+    parseNar(narResult.data);
+
+    for (const extensionElement of extensionManifest.querySelectorAll("extensionManifest > extensions > extension")) {
+        const extensionResult = await NarExtensionSchema.safeParseAsync({
+            narId: narResult.data.name,
+            name: querySelectorString(extensionElement, "name"),
+            type: querySelectorString(extensionElement, "type"),
+            description: querySelectorString(extensionElement, "description"),
+            writesAttributes: [],
+            readsAttributes: [],
+            tags: [],
+            properties: [],
+            relationships: [],
+            required: querySelectorBoolean(extensionElement, "required"),
+            sensitive: querySelectorBoolean(extensionElement, "sensitive"),
+            expressionLanguageSupported: querySelectorBoolean(extensionElement, "expressionLanguageSupported"),
+            expressionLanguageScope: querySelectorString(extensionElement, "expressionLanguageScope"),
+            dynamicallyModifiesClasspath: querySelectorBoolean(extensionElement, "dynamicallyModifiesClasspath"),
+            dynamic: querySelectorBoolean(extensionElement, "dynamic"),
+        });        
+
+        if (!extensionResult.success) {
+            console.error({
+                file: file.name,
+                type: "Unable to parse NarExtensionSchema",
+                error: extensionResult.error,
+            });
+            continue;
+        }
+
+        for(const tagElement of extensionElement.querySelectorAll("tags > tag")) {
+            if(tagElement.textContent) {
+                extensionResult.data.tags.push(tagElement.textContent);
+            }
+        }
+
+        for(const propertyElement of extensionElement.querySelectorAll("properties > property")) {
+            if(propertyElement.textContent) {
+                const raw = await NarExtensionProperty.parseAsync({
+                    name: querySelectorString(propertyElement, "name"),
+                    description: querySelectorString(propertyElement, "description"),
+                    displayName: querySelectorString(propertyElement, "displayName"),
+                })
+
+                extensionResult.data.properties.push(raw);
+            }
+        }
+
+        for(const relationshipElement of extensionElement.querySelectorAll("relationships > relationship")) {
+            if(relationshipElement.textContent) {
+                const raw = await NarExtensionRelationship.parseAsync({
+                    name: querySelectorString(relationshipElement, "name"),
+                    description: querySelectorString(relationshipElement, "description"),
+                    autoTerminated: querySelectorBoolean(relationshipElement, "autoTerminated"),
+                })
+
+                extensionResult.data.relationships.push(raw);
+            }
+        }
+
+        parseExtension(extensionResult.data);
+
+        for (const {type, selectors} of attributesLut) {
+            const queryResult = extensionElement.querySelectorAll(selectors);
+
+            for (const attributeElement of queryResult) {
+                const name = attributeElement.querySelector("name")?.textContent || undefined;
+
+                const rawAttribute: Partial<NarAttribute> = {
+                    narId: narResult.data.name,
+                    extensionId: extensionResult.data.name,
+                    id: `${extensionResult.data.name}|${name}`,
+                    type: type,
+                    name: name,
+                    description: attributeElement.querySelector("description")?.textContent || undefined,
+                }
+
+                const attributeResult = await NarAttributeSchema.safeParseAsync(rawAttribute)
+                
+                if(!attributeResult.success) {
+                    console.error({
+                        file: file.name,
+                        type: "Unable to parse NarAttributeSchema",
+                        error: attributeResult.error,
+                    });
+                    continue;
+                }
+
+                parseAttribute(attributeResult.data);
+            }
+        }
+    }
+
+    return narResult;
+}
+
+export type ReadNarsResult = {
+    readonly filesLength: number
+    filesCount: number
+    narCount: number
+    narSuccessCount: number
+    narErrorCount: number
+}
+
+export async function readNars({files, options, setCurrentProgress, parseNar, parseExtension, parseAttribute, DOMParser}: ReadNarsParameters): Promise<ReadNarsResult> {
+    const result: ReadNarsResult = {
+        filesLength: files.length,
+        filesCount: 0,
+        narCount: 0,
+        narSuccessCount: 0,
+        narErrorCount: 0,
+    }
+    setCurrentProgress(0, result.filesLength);
+    for (let index = 0; index < result.filesLength; index++) {
+        result.filesCount += 1;
+        setCurrentProgress(index, result.filesLength);
+
+        const file = files[index];
+        if (file == null || file == undefined) {
+            console.error({
+                type: "Non-File object",
+                file: file,
+            });
+            continue;
+        } 
+        if(! (file instanceof File)) {
+            result.narErrorCount += 1;
+            console.error({
+                type: "Non-File object",
+                file: file,
+            });
+            continue;
+        }
+        if (!file.name.endsWith(".nar")) {
+            continue;
+        }
+        result.narCount += 1;
+
+        await JSZip.loadAsync(await file.arrayBuffer(), options).then(async (zipFile) => {
+            //TODO: Actually use manifestFile
+            const manifestFile = zipFile.files["META-INF/MANIFEST.MF"];
+            const manifestResult = await manifestFile.async("text").then(manifest => {
+                return manifest.split("\n").map(line => {
+                    const index = line.indexOf(":");
+                    return [line.substring(0, index).trim(), line.substring(index + 1).trim()]
+                }).filter(x => x[0].length > 0 || x[1].length > 0);
+            }).then(Object.fromEntries).then(ManifestSchema.safeParseAsync);
+
+            if(!manifestResult.success) {
+                result.narErrorCount +=1;
+                console.error({
+                    file: file.name,
+                    type: "Unable to parse ManifestSchema",
+                    error: manifestResult.error,
+                });
+                return null;
+            }
+
+            const extensionManifestFile = zipFile.files["META-INF/docs/extension-manifest.xml"];
+            if (extensionManifestFile == undefined) {
+                result.narErrorCount +=1;
+                console.error({
+                    file: file.name,
+                    type: "Manifest file does not exist",
+                });
+                return null;
+            }
+
+            return await extensionManifestFile.async("text").then(async (xml) => {
+                const extensionManifestFile = DOMParser.parseFromString(xml, "text/xml");
+                return await readExtensionManifest({
+                    file, 
+                    parseNar, 
+                    parseExtension, 
+                    parseAttribute,
+                    manifest: manifestResult.data,
+                    extensionManifest: extensionManifestFile,
+                });
+            })
+        }).catch((e) => {
+            result.narErrorCount +=1;
+            console.error({
+                fileName: file.name,
+                file: file,
+                type: "Uncaught Error",
+                error: e,
+            })
+        });
+    }
+
+    setCurrentProgress(files.length, files.length);
+
+    return result;
+}
+
+export const WriteNarsSchema = z.object({
+    nars: NarsSchema,
+    extensions: NarExtensionsSchema,
+    attributes: NarAttributesSchema,
+})
+
+export type WriteNars = z.infer<typeof WriteNarsSchema>;

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    // TODO: Added DOM, because some imports weren't working on GitHub Actions (Blob, AlgorithmIdentifier, etc)
+    "lib": ["es2022", "DOM", "dom.iterable"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: [ "src/main.ts" ],
+    target: 'es2020',
+    format: ['cjs', 'esm'],
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    dts: true
+})