expo-modules-macros 0.26.0 → 0.27.0

package/apple/Sources/ExpoModulesMacros/{TupleTypes.swift → Support/TupleTypes.swift}

@@ -50,29 +50,60 @@ internal enum TupleConversion {
     }
   }
 
-  /// The encode expression, as it appears after `try`, for the value `valueExpression` in the runtime
-  /// named `runtime`. A tuple whose elements all conform needs no closures. The tuple method takes an
-  /// unlabeled tuple, so a labeled one is coerced to its unlabeled type first.
-  func encodeExpression(of valueExpression: String, in runtime: String = "runtime") -> String {
+  /// The call, as it appears after `try`, that encodes the value `valueExpression` into the slot named
+  /// `slot`, in the runtime named `runtime`. A tuple whose elements all conform needs no closures. The
+  /// tuple method takes an unlabeled tuple, so a labeled one is coerced to its unlabeled type first.
+  func encodeCall(of valueExpression: String, into slot: String, in runtime: String = "runtime") -> String {
     switch self {
     case .conforming(let type):
-      return "\(expressionType(type)).encode(\(valueExpression), in: \(runtime))"
+      return "\(expressionType(type)).encode(\(valueExpression), into: \(slot), in: \(runtime))"
     case .tuple(let elements, let labels):
       let value = labels == nil ? valueExpression : "\(valueExpression) as \(unlabeledType)"
       let closures =
         conformingElementTypes(elements) == nil
-        ? elements.map { elementClosure(returning: $0.encodeExpression(of: "value")) } : []
-      let arguments = [value] + labelsArgument(labels) + ["in: \(runtime)"] + closures
+        ? elements.map { encoderClosure(encoding: $0.encodeCall(of: "value", into: "slot")) } : []
+      let arguments = [value] + labelsArgument(labels) + ["into: \(slot)", "in: \(runtime)"] + closures
       return "JavaScriptValue.encodeTuple(\(arguments.joined(separator: ", ")))"
     case .optional(let wrapped):
-      return containerEncode("encodeOptional", label: "wrapped", inner: wrapped, of: valueExpression, in: runtime)
+      return containerEncode(
+        "encodeOptional",
+        label: "wrapped",
+        inner: wrapped,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
     case .array(let element):
-      return containerEncode("encodeArray", label: "element", inner: element, of: valueExpression, in: runtime)
+      return containerEncode(
+        "encodeArray",
+        label: "element",
+        inner: element,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
     case .dictionary(let value):
-      return containerEncode("encodeDictionary", label: "value", inner: value, of: valueExpression, in: runtime)
+      return containerEncode(
+        "encodeDictionary",
+        label: "value",
+        inner: value,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
     }
   }
 
+  /// The encode expression, as it appears after `try`, that creates a `JavaScriptValue` from the value
+  /// `valueExpression`, for a place that has no slot to encode into, such as an async result. A type that
+  /// holds a tuple is encoded into the slot of `JavaScriptValue.encoding(in:_:)`.
+  func encodeExpression(of valueExpression: String) -> String {
+    if case .conforming(let type) = self {
+      return "\(expressionType(type)).encode(\(valueExpression), in: runtime)"
+    }
+    return "JavaScriptValue.encoding(in: runtime) { slot in try \(encodeCall(of: valueExpression, into: "slot")) }"
+  }
+
   /// The JavaScript value kinds the decode accepts, as an expression of type `JavaScriptValueKinds`, for
   /// a `@Union` that picks a payload by kind. Mirrors the kinds of the matching `JavaScriptCodable`
   /// conformances: an array decodes a non-array value as a single element.
@@ -147,10 +178,11 @@ internal enum TupleConversion {
     label: String,
     inner: TupleConversion,
     of valueExpression: String,
+    into slot: String,
     in runtime: String
   ) -> String {
-    return
-      "JavaScriptValue.\(method)(\(valueExpression), in: \(runtime), \(label): \(elementClosure(returning: inner.encodeExpression(of: "value"))))"
+    let closure = encoderClosure(encoding: inner.encodeCall(of: "value", into: "slot"))
+    return "JavaScriptValue.\(method)(\(valueExpression), into: \(slot), in: \(runtime), \(label): \(closure))"
   }
 
   /// The types of a tuple's elements when every element converts through its own `decode` /
@@ -232,3 +264,9 @@ private func structure(of type: TypeSyntax) -> TupleConversion {
 internal func elementClosure(returning expression: String) -> String {
   return "{ value, runtime in return try \(expression) }"
 }
+
+/// An element closure that encodes its value into its slot with `call`, as it appears after `try`. It takes
+/// the value, the slot and the runtime as parameters, which shadow the outer ones, so it captures nothing.
+internal func encoderClosure(encoding call: String) -> String {
+  return "{ value, slot, runtime in try \(call) }"
+}

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { ScanExportsResult, ScanModulesResult } from './types';
+import { ExpandResult, ScanExportsResult, ScanModulesResult } from './types';
 export * from './types';
 /** Options accepted by `scanModules`, mirroring the CLI's `scan-modules` flags. */
 export interface ScanModulesOptions {
@@ -19,6 +19,21 @@ export interface ScanExportsOptions {
     /** Milliseconds after which the scanner is killed and the scan fails. No limit by default. */
     timeout?: number;
 }
+/** Options accepted by `expandMacros`, mirroring the CLI's `expand` flags. */
+export interface ExpandMacrosOptions {
+    /**
+     * Limits the result to these symbols: a type (`'MyModule'`, `'MyModule.Options'`) or a member
+     * (`'MyModule.greet'`). A member expands its type with only the declarations of that name. Each
+     * symbol must be declared in one of the files, or the call fails with a `ScannerError`.
+     */
+    symbols?: string[];
+    /** Returns only the diagnostics, with no expansions. */
+    diagnosticsOnly?: boolean;
+    /** Overrides the scanner binary path. Defaults to the one shipped with this package. */
+    binaryPath?: string;
+    /** Milliseconds after which the scanner is killed and the call fails. No limit by default. */
+    timeout?: number;
+}
 /**
  * Thrown when the scanner exits non-zero. Exit code 2 is a usage error (bad subcommand or flags) and
  * 1 means the report couldn't be encoded; both put a message on stderr, carried here as `stderr`.
@@ -68,3 +83,18 @@ export declare function scanModules(paths: string[], options?: ScanModulesOption
  * what it guards is not reported.
  */
 export declare function scanExports(paths: string[], options?: ScanExportsOptions): Promise<ScanExportsResult>;
+/**
+ * Expands the Expo macros in process, without a build, and returns the generated
+ * code with the syntax errors and the macro diagnostics. The macros only read the syntax tree, so
+ * the code is what the compiler gets, except for the names that a macro makes unique. Errors that
+ * need type checking, for example a type that doesn't conform to a protocol, still need a build.
+ *
+ * Each path is a `.swift` file, which is always expanded and keeps its path in the result, or a
+ * directory. A directory is walked like the scans walk it, and only its files that use one of the
+ * macros are expanded, with their absolute paths.
+ *
+ * Error diagnostics don't make the call fail: check `severity` in `diagnostics`. Only an input that
+ * can't be expanded (a missing path, a file that isn't Swift, a symbol that no file declares) throws
+ * a `ScannerError`.
+ */
+export declare function expandMacros(paths: string[], options?: ExpandMacrosOptions): Promise<ExpandResult>;

package/build/index.js

@@ -21,6 +21,7 @@ exports.ScannerSchemaVersionError = exports.ScannerError = void 0;
 exports.getScannerBinaryPath = getScannerBinaryPath;
 exports.scanModules = scanModules;
 exports.scanExports = scanExports;
+exports.expandMacros = expandMacros;
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const types_1 = require("./types");
@@ -210,3 +211,36 @@ async function scanExports(paths, options = {}) {
     }
     return result;
 }
+/**
+ * Expands the Expo macros in process, without a build, and returns the generated
+ * code with the syntax errors and the macro diagnostics. The macros only read the syntax tree, so
+ * the code is what the compiler gets, except for the names that a macro makes unique. Errors that
+ * need type checking, for example a type that doesn't conform to a protocol, still need a build.
+ *
+ * Each path is a `.swift` file, which is always expanded and keeps its path in the result, or a
+ * directory. A directory is walked like the scans walk it, and only its files that use one of the
+ * macros are expanded, with their absolute paths.
+ *
+ * Error diagnostics don't make the call fail: check `severity` in `diagnostics`. Only an input that
+ * can't be expanded (a missing path, a file that isn't Swift, a symbol that no file declares) throws
+ * a `ScannerError`.
+ */
+async function expandMacros(paths, options = {}) {
+    if (paths.length === 0) {
+        throw new TypeError('expandMacros requires at least one path');
+    }
+    assertRepresentablePaths('expandMacros', paths);
+    const args = ['expand', '--json'];
+    for (const symbol of options.symbols ?? []) {
+        args.push('--symbol', symbol);
+    }
+    if (options.diagnosticsOnly) {
+        args.push('--diagnostics-only');
+    }
+    args.push(...paths);
+    const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), args, options.timeout);
+    if (result.schemaVersion !== types_1.SUPPORTED_EXPAND_SCHEMA_VERSION) {
+        throw new ScannerSchemaVersionError('expand', result.schemaVersion, types_1.SUPPORTED_EXPAND_SCHEMA_VERSION);
+    }
+    return result;
+}

package/build/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Hand-written mirrors of the scanner's JSON output. The Swift `Codable` types in
- * `apple/Sources/ExpoModulesScanner` are the source of truth; these are kept in sync by hand, which
+ * `apple/Sources/ExpoModulesCLI` are the source of truth; these are kept in sync by hand, which
  * is why each command carries a `schemaVersion` the wrapper checks at runtime.
  */
 /** The JS `typeof` category a boundary type reports, mirroring `JSType`. */
@@ -414,6 +414,49 @@ export interface ScanExportsResult {
     exports: ExportedSurface;
     stats: ScanStats;
 }
+/** A note attached to an `ExpansionDiagnostic`, at its own location. */
+export interface ExpansionNote {
+    message: string;
+    line: number;
+    column: number;
+}
+/**
+ * A syntax error in a file or a diagnostic of a macro, at its location in the original file. `line`
+ * and `column` are 1-based, and the column counts UTF-8 bytes, as in the compiler's output.
+ */
+export interface ExpansionDiagnostic {
+    severity: 'error' | 'warning' | 'note' | 'remark';
+    message: string;
+    line: number;
+    column: number;
+    notes: ExpansionNote[];
+    /** The messages of the Fix-Its, for example `replace 'var' with 'let'`. */
+    fixIts: string[];
+}
+/** Expanded source code. */
+export interface Expansion {
+    /** The symbol this expansion is for, or absent for the whole file. */
+    symbol?: string;
+    source: string;
+}
+/** What the macros generate for one file, and what they report about it. */
+export interface ExpandedFile {
+    /** The path as it was passed, or the absolute path of a file found in a directory. */
+    file: string;
+    /**
+     * Without symbols, one expansion of the whole file. With symbols, one per symbol that this file
+     * declares, in the order they were passed. Empty with `diagnosticsOnly`.
+     */
+    expansions: Expansion[];
+    /** In source order. With symbols, only those inside the declarations of the symbols. */
+    diagnostics: ExpansionDiagnostic[];
+}
+/** The `expand --json` result. */
+export interface ExpandResult {
+    schemaVersion: number;
+    /** One entry per expanded file: the files in the order they were passed, a directory's files sorted. */
+    files: ExpandedFile[];
+}
 /**
  * The output schema versions this package was written against. The wrapper compares these to the
  * `schemaVersion` in each report and throws on a mismatch, so a binary/wrapper version skew surfaces
@@ -421,3 +464,4 @@ export interface ScanExportsResult {
  */
 export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
 export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 10;
+export declare const SUPPORTED_EXPAND_SCHEMA_VERSION = 1;

package/build/types.js

@@ -1,11 +1,11 @@
 "use strict";
 /**
  * Hand-written mirrors of the scanner's JSON output. The Swift `Codable` types in
- * `apple/Sources/ExpoModulesScanner` are the source of truth; these are kept in sync by hand, which
+ * `apple/Sources/ExpoModulesCLI` are the source of truth; these are kept in sync by hand, which
  * is why each command carries a `schemaVersion` the wrapper checks at runtime.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = void 0;
+exports.SUPPORTED_EXPAND_SCHEMA_VERSION = exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = void 0;
 /**
  * The output schema versions this package was written against. The wrapper compares these to the
  * `schemaVersion` in each report and throws on a mismatch, so a binary/wrapper version skew surfaces
@@ -13,3 +13,4 @@ exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_S
  */
 exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
 exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 10;
+exports.SUPPORTED_EXPAND_SCHEMA_VERSION = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-macros",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Swift macro plugin for Expo modules",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -26,9 +26,9 @@
     "typescript": "^5.4.0"
   },
   "optionalDependencies": {
-    "@expo/modules-macros-linux-arm64": "0.26.0",
-    "@expo/modules-macros-linux-x64": "0.26.0",
-    "@expo/modules-macros-win32-arm64": "0.26.0",
-    "@expo/modules-macros-win32-x64": "0.26.0"
+    "@expo/modules-macros-linux-arm64": "0.27.0",
+    "@expo/modules-macros-linux-x64": "0.27.0",
+    "@expo/modules-macros-win32-arm64": "0.27.0",
+    "@expo/modules-macros-win32-x64": "0.27.0"
   }
 }