nitrogen 0.2.23 → 0.29.4

package/lib/syntax/Property.d.ts

@@ -0,0 +1,50 @@
+import type { CodeNode } from './CodeNode.js';
+import { type SourceFile, type SourceImport } from './SourceFile.js';
+import type { Language } from '../getPlatformSpecs.js';
+import type { Type } from './types/Type.js';
+import { Method } from './Method.js';
+export interface PropertyBody {
+    getter: string;
+    setter: string;
+}
+export type LanguageEnvironment = 'jvm' | 'swift' | 'other';
+export interface PropertyModifiers {
+    /**
+     * The name of the class that defines this C++ property getter/setter method.
+     * Example: `Person` -> `int Person::getAge()`
+     */
+    classDefinitionName?: string;
+    /**
+     * Whether the property should be marked as inlineable.
+     */
+    inline?: boolean;
+    virtual?: boolean;
+    /**
+     * Whether the property is marked as `noexcept` (doesn't throw) or not.
+     */
+    noexcept?: boolean;
+    /**
+     * Whether this property overrides a base/super property.
+     */
+    override?: boolean;
+    /**
+     * Whether this property has a `@DoNotStrip` and `@Keep` attribute to avoid
+     * it from being stripped from the binary by the Java compiler or ProGuard.
+     */
+    doNotStrip?: boolean;
+}
+export declare class Property implements CodeNode {
+    readonly name: string;
+    readonly type: Type;
+    readonly isReadonly: boolean;
+    constructor(name: string, type: Type, isReadonly: boolean);
+    get jsSignature(): string;
+    getExtraFiles(): SourceFile[];
+    getRequiredImports(language: Language): SourceImport[];
+    getGetterName(environment: LanguageEnvironment): string;
+    getSetterName(environment: LanguageEnvironment): string;
+    get cppGetter(): Method;
+    get cppSetter(): Method | undefined;
+    getCppMethods(): [getter: Method] | [getter: Method, setter: Method];
+    getCode(language: Language, modifiers?: PropertyModifiers, body?: PropertyBody): string;
+}

package/lib/syntax/Property.js

@@ -0,0 +1,147 @@
+import { capitalizeName } from '../utils.js';
+import {} from './SourceFile.js';
+import { Method } from './Method.js';
+import { VoidType } from './types/VoidType.js';
+import { Parameter } from './Parameter.js';
+import { isBooleanPropertyPrefix } from './helpers.js';
+export class Property {
+    name;
+    type;
+    isReadonly;
+    constructor(name, type, isReadonly) {
+        this.name = name;
+        this.type = type;
+        this.isReadonly = isReadonly;
+        if (this.name.startsWith('__')) {
+            throw new Error(`Property names are not allowed to start with two underscores (__)! (In ${this.jsSignature})`);
+        }
+    }
+    get jsSignature() {
+        return `${this.name}: ${this.type.kind}`;
+    }
+    getExtraFiles() {
+        return this.type.getExtraFiles();
+    }
+    getRequiredImports(language) {
+        return this.type.getRequiredImports(language);
+    }
+    getGetterName(environment) {
+        if (this.type.kind === 'boolean' && isBooleanPropertyPrefix(this.name)) {
+            // Boolean accessors where the property starts with "is" or "has" are renamed in JVM and Swift
+            switch (environment) {
+                case 'jvm':
+                case 'swift':
+                    // isSomething -> isSomething()
+                    return this.name;
+                default:
+                    break;
+            }
+        }
+        // isSomething -> getIsSomething()
+        return `get${capitalizeName(this.name)}`;
+    }
+    getSetterName(environment) {
+        if (this.type.kind === 'boolean' && this.name.startsWith('is')) {
+            // Boolean accessors where the property starts with "is" are renamed in JVM
+            if (environment === 'jvm') {
+                // isSomething -> setSomething()
+                const cleanName = this.name.replace('is', '');
+                return `set${capitalizeName(cleanName)}`;
+            }
+        }
+        // isSomething -> setIsSomething()
+        return `set${capitalizeName(this.name)}`;
+    }
+    get cppGetter() {
+        return new Method(this.getGetterName('other'), this.type, []);
+    }
+    get cppSetter() {
+        if (this.isReadonly)
+            return undefined;
+        const parameter = new Parameter(this.name, this.type);
+        return new Method(this.getSetterName('other'), new VoidType(), [parameter]);
+    }
+    getCppMethods() {
+        if (this.cppSetter != null) {
+            // get + set
+            return [this.cppGetter, this.cppSetter];
+        }
+        else {
+            // get
+            return [this.cppGetter];
+        }
+    }
+    getCode(language, modifiers, body) {
+        if (body != null) {
+            body.getter = body.getter.trim();
+            body.setter = body.setter.trim();
+        }
+        switch (language) {
+            case 'c++': {
+                const methods = this.getCppMethods();
+                const [getter, setter] = methods;
+                const lines = [];
+                lines.push(getter.getCode('c++', modifiers, body?.getter));
+                if (setter != null) {
+                    lines.push(setter.getCode('c++', modifiers, body?.setter));
+                }
+                return lines.join('\n');
+            }
+            case 'swift': {
+                const type = this.type.getCode('swift');
+                let accessors;
+                if (body == null) {
+                    accessors = this.isReadonly ? `get` : `get set`;
+                }
+                else {
+                    const lines = [];
+                    lines.push(`
+get {
+  ${body.getter}
+}
+          `);
+                    if (!this.isReadonly) {
+                        lines.push(`
+set {
+  ${body.setter}
+}
+            `);
+                    }
+                    accessors = '\n' + lines.join('\n') + '\n';
+                }
+                return `var ${this.name}: ${type} { ${accessors} }`;
+            }
+            case 'kotlin': {
+                const type = this.type.getCode('kotlin');
+                let keyword = this.isReadonly ? 'val' : 'var';
+                if (modifiers?.virtual)
+                    keyword = `abstract ${keyword}`;
+                const lines = [];
+                if (modifiers?.doNotStrip) {
+                    lines.push('@get:DoNotStrip', '@get:Keep');
+                    if (!this.isReadonly) {
+                        lines.push('@set:DoNotStrip', '@set:Keep');
+                    }
+                }
+                lines.push(`${keyword} ${this.name}: ${type}`);
+                if (body != null) {
+                    lines.push(`
+  get() {
+    ${body.getter}
+  }
+          `);
+                    if (!this.isReadonly) {
+                        lines.push(`
+  set(value) {
+    ${body.setter}
+  }
+            `);
+                    }
+                }
+                return lines.join('\n');
+            }
+            default:
+                throw new Error(`Language ${language} is not yet supported for properties!`);
+        }
+    }
+}

package/lib/syntax/SourceFile.d.ts

@@ -0,0 +1,70 @@
+import type { Language, Platform } from '../getPlatformSpecs.js';
+import type { Type } from './types/Type.js';
+/**
+ * Represents a file with source code, in a specific programming language.
+ */
+export interface SourceFile {
+    /**
+     * The name of the file with extension (e.g. `Image.hpp`)
+     */
+    name: string;
+    /**
+     * The subdirectory/subdirectories of the file, or empty (`[]`) if none.
+     */
+    subdirectory: string[];
+    /**
+     * The full content of the file.
+     */
+    content: string;
+    /**
+     * The language the {@linkcode content} is written in (e.g. `c++`)
+     */
+    language: Language;
+    /**
+     * The platform this file can be used on or is created for. (e.g. `ios`)
+     */
+    platform: Platform | 'shared';
+}
+/**
+ * Represents a {@linkcode SourceFile} that also references other types.
+ */
+export interface FileWithReferencedTypes extends SourceFile {
+    /**
+     * All external types this {@linkcode SourceFile} references,
+     * either as return types, parameter types, or member types.
+     */
+    referencedTypes: Type[];
+}
+/**
+ * Represents an import for a specific header or module.
+ *
+ * E.g. `include "Image.hpp"`, or `import NitroModules`
+ */
+export interface SourceImport {
+    /**
+     * The name of the header or module to import (e.g. `Image.hpp`)
+     */
+    name: string;
+    /**
+     * If this is a C++ import, it could also be forward-declared.
+     * @example
+     * ```cpp
+     * namespace NitroTest {
+     *   class HybridImage;
+     * }
+     * ```
+     */
+    forwardDeclaration?: string;
+    /**
+     * The language this file is written in (e.g. `c++`)
+     */
+    language: Language;
+    /**
+     * Whether the import is a user-defined header (something local, like `"MyObject.hpp"`)
+     * or a shared system header (like `<NitroModules/HybridObject.hpp>`)
+     */
+    space: 'user' | 'system';
+}
+type GroupedFiles = Record<SourceFile['platform'], SourceFile[]>;
+export declare function groupByPlatform(files: SourceFile[]): GroupedFiles;
+export {};

package/lib/syntax/SourceFile.js

@@ -0,0 +1,7 @@
+export function groupByPlatform(files) {
+    const result = { shared: [], ios: [], android: [] };
+    for (const file of files) {
+        result[file.platform].push(file);
+    }
+    return result;
+}

package/lib/syntax/c++/CppEnum.d.ts

@@ -0,0 +1,6 @@
+import type { SourceFile } from '../SourceFile.js';
+import type { EnumMember } from '../types/EnumType.js';
+/**
+ * Creates a C++ enum that converts to a JS enum (aka just int)
+ */
+export declare function createCppEnum(typename: string, enumMembers: EnumMember[]): SourceFile;

package/lib/syntax/c++/CppEnum.js

@@ -0,0 +1,110 @@
+import { NitroConfig } from '../../config/NitroConfig.js';
+import { indent, toLowerCamelCase } from '../../utils.js';
+import { createFileMetadataString } from '../helpers.js';
+import { includeNitroHeader } from './includeNitroHeader.js';
+function getEnumMinValue(enumMembers) {
+    return Math.min(...enumMembers.map((m) => m.value));
+}
+function getEnumMaxValue(enumMembers) {
+    return Math.max(...enumMembers.map((m) => m.value));
+}
+function isIncrementingEnum(enumMembers) {
+    let lastValue = getEnumMinValue(enumMembers) - 1;
+    for (const enumMember of enumMembers) {
+        if (enumMember.value !== lastValue + 1) {
+            // it is not just one higher than the last value!
+            return false;
+        }
+        lastValue = enumMember.value;
+    }
+    // all enum values were incrementing!
+    return true;
+}
+/**
+ * Creates a C++ enum that converts to a JS enum (aka just int)
+ */
+export function createCppEnum(typename, enumMembers) {
+    // Namespace typename
+    const fullyQualifiedTypename = NitroConfig.current.getCxxNamespace('c++', typename);
+    // Map enum to C++ code
+    const cppEnumMembers = enumMembers
+        .map((m) => `${m.name}      SWIFT_NAME(${toLowerCamelCase(m.name)}) = ${m.value},`)
+        .join('\n');
+    const cxxNamespace = NitroConfig.current.getCxxNamespace('c++');
+    let isInsideValidValues;
+    if (isIncrementingEnum(enumMembers)) {
+        // It's just incrementing one after another, so we can simplify this to a bounds check
+        const minValue = getEnumMinValue(enumMembers);
+        const maxValue = getEnumMaxValue(enumMembers);
+        isInsideValidValues = `
+// Check if we are within the bounds of the enum.
+return integer >= ${minValue} && integer <= ${maxValue};
+    `.trim();
+    }
+    else {
+        const cases = enumMembers.map((m) => `case ${m.value} /* ${m.name} */: return true;`);
+        isInsideValidValues = `
+switch (integer) {
+  ${indent(cases.join('\n'), '  ')}
+  default: return false;
+}
+    `.trim();
+    }
+    // Create entire C++ file
+    const cppCode = `
+${createFileMetadataString(`${typename}.hpp`)}
+
+#pragma once
+
+${includeNitroHeader('JSIConverter.hpp')}
+${includeNitroHeader('NitroDefines.hpp')}
+
+namespace ${cxxNamespace} {
+
+  /**
+   * An enum which can be represented as a JavaScript enum (${typename}).
+   */
+  enum class ${typename} {
+    ${indent(cppEnumMembers, '    ')}
+  } CLOSED_ENUM;
+
+} // namespace ${cxxNamespace}
+
+namespace margelo::nitro {
+
+  // C++ ${typename} <> JS ${typename} (enum)
+  template <>
+  struct JSIConverter<${fullyQualifiedTypename}> final {
+    static inline ${fullyQualifiedTypename} fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      int enumValue = JSIConverter<int>::fromJSI(runtime, arg);
+      return static_cast<${fullyQualifiedTypename}>(enumValue);
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, ${fullyQualifiedTypename} arg) {
+      int enumValue = static_cast<int>(arg);
+      return JSIConverter<int>::toJSI(runtime, enumValue);
+    }
+    static inline bool canConvert(jsi::Runtime&, const jsi::Value& value) {
+      if (!value.isNumber()) {
+        return false;
+      }
+      double number = value.getNumber();
+      int integer = static_cast<int>(number);
+      if (number != integer) {
+        // The integer is not the same value as the double - we truncated floating points.
+        // Enums are all integers, so the input floating point number is obviously invalid.
+        return false;
+      }
+      ${indent(isInsideValidValues, '      ')}
+    }
+  };
+
+} // namespace margelo::nitro
+        `;
+    return {
+        content: cppCode,
+        subdirectory: [],
+        name: `${typename}.hpp`,
+        language: 'c++',
+        platform: 'shared',
+    };
+}

package/lib/syntax/c++/CppHybridObject.d.ts

@@ -0,0 +1,3 @@
+import type { SourceFile } from '../SourceFile.js';
+import type { HybridObjectSpec } from '../HybridObjectSpec.js';
+export declare function createCppHybridObject(spec: HybridObjectSpec): SourceFile[];

package/lib/syntax/c++/CppHybridObject.js

@@ -0,0 +1,146 @@
+import { createFileMetadataString, isNotDuplicate } from '../helpers.js';
+import { indent } from '../../utils.js';
+import { includeHeader, includeNitroHeader } from './includeNitroHeader.js';
+import { getHybridObjectName } from '../getHybridObjectName.js';
+import { HybridObjectType } from '../types/HybridObjectType.js';
+export function createCppHybridObject(spec) {
+    // Extra includes
+    const extraFiles = [
+        ...spec.properties.flatMap((p) => p.getExtraFiles()),
+        ...spec.methods.flatMap((m) => m.getExtraFiles()),
+    ];
+    const extraIncludes = [
+        ...spec.properties.flatMap((p) => p.getRequiredImports('c++')),
+        ...spec.methods.flatMap((m) => m.getRequiredImports('c++')),
+        ...spec.baseTypes.flatMap((b) => new HybridObjectType(b).getRequiredImports('c++')),
+    ];
+    const cppForwardDeclarations = extraIncludes
+        .map((i) => i.forwardDeclaration)
+        .filter((v) => v != null)
+        .filter(isNotDuplicate);
+    const cppExtraIncludes = extraIncludes
+        .map((i) => includeHeader(i))
+        .filter(isNotDuplicate);
+    const cxxNamespace = spec.config.getCxxNamespace('c++');
+    const name = getHybridObjectName(spec.name);
+    const bases = ['public virtual HybridObject'];
+    for (const base of spec.baseTypes) {
+        const baseName = getHybridObjectName(base.name).HybridTSpec;
+        const fullName = base.config.isExternalConfig
+            ? base.config.getCxxNamespace('c++', baseName)
+            : baseName;
+        bases.push(`public virtual ${fullName}`);
+    }
+    // Generate the full header / code
+    const cppHeaderCode = `
+${createFileMetadataString(`${name.HybridTSpec}.hpp`)}
+
+#pragma once
+
+${includeNitroHeader('HybridObject.hpp')}
+
+${cppForwardDeclarations.join('\n')}
+
+${cppExtraIncludes.join('\n')}
+
+namespace ${cxxNamespace} {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for \`${spec.name}\`
+   * Inherit this class to create instances of \`${name.HybridTSpec}\` in C++.
+   * You must explicitly call \`HybridObject\`'s constructor yourself, because it is virtual.
+   * @example
+   * \`\`\`cpp
+   * class ${name.HybridT}: public ${name.HybridTSpec} {
+   * public:
+   *   ${name.HybridT}(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * \`\`\`
+   */
+  class ${name.HybridTSpec}: ${bases.join(', ')} {
+    public:
+      // Constructor
+      explicit ${name.HybridTSpec}(): HybridObject(TAG) { }
+
+      // Destructor
+      ~${name.HybridTSpec}() override = default;
+
+    public:
+      // Properties
+      ${indent(spec.properties.map((p) => p.getCode('c++', { virtual: true })).join('\n'), '      ')}
+
+    public:
+      // Methods
+      ${indent(spec.methods.map((m) => m.getCode('c++', { virtual: true })).join('\n'), '      ')}
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "${spec.name}";
+  };
+
+} // namespace ${cxxNamespace}
+    `;
+    // Each C++ method needs to be registered in the HybridObject - that's getters, setters and normal methods.
+    const registrations = [];
+    for (const property of spec.properties) {
+        const getterMethod = property.getGetterName('other');
+        const setterMethod = property.getSetterName('other');
+        // getter
+        registrations.push(`prototype.registerHybridGetter("${property.name}", &${name.HybridTSpec}::${getterMethod});`);
+        if (!property.isReadonly) {
+            // setter
+            registrations.push(`prototype.registerHybridSetter("${property.name}", &${name.HybridTSpec}::${setterMethod});`);
+        }
+    }
+    for (const method of spec.methods) {
+        // method
+        registrations.push(`prototype.registerHybridMethod("${method.name}", &${name.HybridTSpec}::${method.name});`);
+    }
+    const basePrototypeRegistrations = ['HybridObject::loadHybridMethods();'];
+    for (const base of spec.baseTypes) {
+        const hybridObjectName = getHybridObjectName(base.name);
+        basePrototypeRegistrations.push(`${hybridObjectName.HybridTSpec}::loadHybridMethods();`);
+    }
+    const cppBodyCode = `
+${createFileMetadataString(`${name.HybridTSpec}.cpp`)}
+
+#include "${name.HybridTSpec}.hpp"
+
+namespace ${cxxNamespace} {
+
+  void ${name.HybridTSpec}::loadHybridMethods() {
+    // load base methods/properties
+    ${indent(basePrototypeRegistrations.join('\n'), '    ')}
+    // load custom methods/properties
+    registerHybrids(this, [](Prototype& prototype) {
+      ${indent(registrations.join('\n'), '      ')}
+    });
+  }
+
+} // namespace ${cxxNamespace}
+    `;
+    const files = [];
+    files.push({
+        content: cppHeaderCode,
+        name: `${name.HybridTSpec}.hpp`,
+        subdirectory: [],
+        language: 'c++',
+        platform: 'shared',
+    });
+    files.push({
+        content: cppBodyCode,
+        name: `${name.HybridTSpec}.cpp`,
+        subdirectory: [],
+        language: 'c++',
+        platform: 'shared',
+    });
+    files.push(...extraFiles);
+    return files;
+}

package/lib/syntax/c++/CppHybridObjectRegistration.d.ts

@@ -0,0 +1,17 @@
+import type { SourceImport } from '../SourceFile.js';
+interface Props {
+    /**
+     * The name of the Hybrid Object under which it should be registered and exposed to JS to.
+     */
+    hybridObjectName: string;
+    /**
+     * The name of the C++ class that will be default-constructed
+     */
+    cppClassName: string;
+}
+interface CppHybridObjectRegistration {
+    cppCode: string;
+    requiredImports: SourceImport[];
+}
+export declare function createCppHybridObjectRegistration({ hybridObjectName, cppClassName, }: Props): CppHybridObjectRegistration;
+export {};

package/lib/syntax/c++/CppHybridObjectRegistration.js

@@ -0,0 +1,18 @@
+export function createCppHybridObjectRegistration({ hybridObjectName, cppClassName, }) {
+    return {
+        requiredImports: [
+            { name: `${cppClassName}.hpp`, language: 'c++', space: 'user' },
+        ],
+        cppCode: `
+HybridObjectRegistry::registerHybridObjectConstructor(
+  "${hybridObjectName}",
+  []() -> std::shared_ptr<HybridObject> {
+    static_assert(std::is_default_constructible_v<${cppClassName}>,
+                  "The HybridObject \\"${cppClassName}\\" is not default-constructible! "
+                  "Create a public constructor that takes zero arguments to be able to autolink this HybridObject.");
+    return std::make_shared<${cppClassName}>();
+  }
+);
+      `.trim(),
+    };
+}

package/lib/syntax/c++/CppStruct.d.ts

@@ -0,0 +1,3 @@
+import type { FileWithReferencedTypes } from '../SourceFile.js';
+import type { NamedType } from '../types/Type.js';
+export declare function createCppStruct(typename: string, properties: NamedType[]): FileWithReferencedTypes;