expo-modules-macros 0.19.1 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/build/index.js CHANGED
@@ -51,12 +51,21 @@ class ScannerSchemaVersionError extends Error {
51
51
  }
52
52
  exports.ScannerSchemaVersionError = ScannerSchemaVersionError;
53
53
  /**
54
- * The package with the Windows binary for the current architecture, for example
55
- * `@expo/modules-macros-win32-x64`. It is an optional dependency of this package, and its `os` and
56
- * `cpu` fields make package managers install it only on a matching Windows machine.
54
+ * The platforms whose binaries ship in packages of their own, one per architecture, with the
55
+ * machines that those packages install on.
57
56
  */
58
- function windowsBinaryPackageName() {
59
- return `@expo/modules-macros-win32-${process.arch}`;
57
+ const platformPackageMachines = {
58
+ win32: 'Windows x64 and arm64',
59
+ linux: 'Linux x64 and arm64 with glibc',
60
+ };
61
+ /**
62
+ * The package with the binary for the current platform and architecture, for example
63
+ * `@expo/modules-macros-win32-x64` or `@expo/modules-macros-linux-arm64`. It is an optional
64
+ * dependency of this package, and its `os`, `cpu` and (on Linux) `libc` fields make package managers
65
+ * install it only on a matching machine.
66
+ */
67
+ function platformBinaryPackageName() {
68
+ return `@expo/modules-macros-${process.platform}-${process.arch}`;
60
69
  }
61
70
  /**
62
71
  * Absolute path to the scanner binary for the current platform. It doubles as the macro plugin
@@ -64,34 +73,40 @@ function windowsBinaryPackageName() {
64
73
  *
65
74
  * - macOS: the universal binary shipped in this package, next to the Swift package rather than in a
66
75
  * `bin` directory.
67
- * - Windows: `ExpoModulesMacros.exe` from the package for the current architecture (see
68
- * `windowsBinaryPackageName`). When that package isn't installed, for example in this repository,
69
- * it falls back to the executable that `npm run build` writes to `platforms/win32-<arch>`.
76
+ * - Windows and Linux: `ExpoModulesMacros.exe` or `ExpoModulesMacros` from the package for the
77
+ * current platform and architecture (see `platformBinaryPackageName`). When that package isn't
78
+ * installed, for example in this repository, it falls back to the executable that `npm run build`
79
+ * writes to `platforms/<platform>-<arch>`.
70
80
  *
71
81
  * The path isn't checked here; running a missing binary fails with a `ScannerError` that says how to
72
82
  * get it.
73
83
  */
74
84
  function getScannerBinaryPath() {
75
- if (process.platform !== 'win32') {
85
+ if (process.platform === 'darwin') {
76
86
  return node_path_1.default.join(__dirname, '..', 'apple', 'ExpoModulesMacros');
77
87
  }
88
+ const fileName = process.platform === 'win32' ? 'ExpoModulesMacros.exe' : 'ExpoModulesMacros';
78
89
  try {
79
- const packageJson = require.resolve(`${windowsBinaryPackageName()}/package.json`);
80
- return node_path_1.default.join(node_path_1.default.dirname(packageJson), 'ExpoModulesMacros.exe');
90
+ const packageJson = require.resolve(`${platformBinaryPackageName()}/package.json`);
91
+ return node_path_1.default.join(node_path_1.default.dirname(packageJson), fileName);
81
92
  }
82
93
  catch {
83
- return node_path_1.default.join(__dirname, '..', 'platforms', `win32-${process.arch}`, 'ExpoModulesMacros.exe');
94
+ return node_path_1.default.join(__dirname, '..', 'platforms', `${process.platform}-${process.arch}`, fileName);
84
95
  }
85
96
  }
86
97
  /** The message for a scanner binary that doesn't exist at `binaryPath`. */
87
98
  function missingBinaryMessage(binaryPath) {
88
- if (process.platform === 'win32') {
89
- return (`The scanner binary is missing at ${binaryPath}. On Windows it comes from the optional package ` +
90
- `${windowsBinaryPackageName()}, which your package manager installs only on Windows x64 and arm64. ` +
91
- 'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
92
- 'or run `npm run build` in this package to build it locally.');
99
+ if (process.platform === 'darwin') {
100
+ return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
93
101
  }
94
- return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
102
+ const machines = platformPackageMachines[process.platform];
103
+ if (machines === undefined) {
104
+ return `The scanner binary is missing at ${binaryPath}. No binary is built for ${process.platform}.`;
105
+ }
106
+ return (`The scanner binary is missing at ${binaryPath}. It comes from the optional package ` +
107
+ `${platformBinaryPackageName()}, which your package manager installs only on ${machines}. ` +
108
+ 'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
109
+ 'or run `npm run build` in this package to build it locally.');
95
110
  }
96
111
  /**
97
112
  * Runs a scanner subcommand and parses its JSON report.
@@ -120,9 +135,11 @@ function assertRepresentablePaths(command, paths) {
120
135
  '`.');
121
136
  }
122
137
  }
123
- function runScanner(binaryPath, args) {
138
+ function runScanner(binaryPath, args, timeout = 0) {
139
+ // The error messages name only the subcommand: the paths can be hundreds of package roots.
140
+ const command = `${node_path_1.default.basename(binaryPath)} ${args[0]}`;
124
141
  return new Promise((resolve, reject) => {
125
- (0, node_child_process_1.execFile)(binaryPath, args, { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' }, (error, stdout, stderr) => {
142
+ const child = (0, node_child_process_1.execFile)(binaryPath, args, { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8', timeout }, (error, stdout, stderr) => {
126
143
  if (error) {
127
144
  // A spawn failure reports a string `code` (e.g. 'ENOENT'); a non-zero exit reports a
128
145
  // number. Only the latter is an exit status.
@@ -131,7 +148,11 @@ function runScanner(binaryPath, args) {
131
148
  reject(new ScannerError(missingBinaryMessage(binaryPath), null, stderr));
132
149
  return;
133
150
  }
134
- reject(new ScannerError(`\`${node_path_1.default.basename(binaryPath)} ${args.join(' ')}\` failed: ${stderr.trim() || error.message}`, exitCode, stderr));
151
+ if (timeout > 0 && error.killed) {
152
+ reject(new ScannerError(`\`${command}\` timed out after ${timeout} ms.`, null, stderr));
153
+ return;
154
+ }
155
+ reject(new ScannerError(`\`${command}\` failed: ${stderr.trim() || error.message}`, exitCode, stderr));
135
156
  return;
136
157
  }
137
158
  try {
@@ -141,6 +162,9 @@ function runScanner(binaryPath, args) {
141
162
  reject(new ScannerError(`Could not parse the scanner's JSON output: ${parseError.message}`, null, stderr));
142
163
  }
143
164
  });
165
+ // The scanner never reads stdin. An executable without the scanner CLI would start the macro
166
+ // plugin server instead and wait on stdin forever.
167
+ child.stdin?.end();
144
168
  });
145
169
  }
146
170
  /**
@@ -160,7 +184,7 @@ async function scanModules(paths, options = {}) {
160
184
  args.push('--define', define);
161
185
  }
162
186
  args.push(...paths);
163
- const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), args);
187
+ const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), args, options.timeout);
164
188
  if (result.schemaVersion !== types_1.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION) {
165
189
  throw new ScannerSchemaVersionError('scan-modules', result.schemaVersion, types_1.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION);
166
190
  }
@@ -170,18 +194,17 @@ async function scanModules(paths, options = {}) {
170
194
  * Deep scan of the full JS-exported surface, for TypeScript type generation. Each path is a `.swift`
171
195
  * file or a directory, scanned recursively.
172
196
  *
173
- * Unlike `scanModules`, this doesn't evaluate `#if` blocks, so it takes no define option:
174
- * conditional declarations are reported as if their conditions held.
197
+ * Each declaration and member reports the Apple OSes whose `#if` conditions and `@available`
198
+ * attributes include it. `#if` is read only where the runtime sees what it holds: around types,
199
+ * `@Event` members, and enum cases. No define option is taken: a condition on a custom flag never holds, so
200
+ * what it guards is not reported.
175
201
  */
176
202
  async function scanExports(paths, options = {}) {
177
203
  if (paths.length === 0) {
178
204
  throw new TypeError('scanExports requires at least one path');
179
205
  }
180
206
  assertRepresentablePaths('scanExports', paths);
181
- const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), [
182
- 'scan-exports',
183
- ...paths,
184
- ]);
207
+ const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), ['scan-exports', ...paths], options.timeout);
185
208
  if (result.schemaVersion !== types_1.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION) {
186
209
  throw new ScannerSchemaVersionError('scan-exports', result.schemaVersion, types_1.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION);
187
210
  }
package/build/types.d.ts CHANGED
@@ -66,6 +66,65 @@ export type TypeNode = {
66
66
  kind: 'unknown';
67
67
  text: string;
68
68
  };
69
+ /**
70
+ * An Apple OS the scanner attributes declarations to, spelled as `os(...)` spells it. The casing is
71
+ * part of the output contract, so consumers with a lowercase convention must fold the case themselves.
72
+ */
73
+ export type ScannedPlatform = 'iOS' | 'macOS' | 'tvOS' | 'watchOS' | 'visionOS';
74
+ /** One Apple OS that builds a declaration in the `scan-exports` output. */
75
+ export interface ExportedPlatform {
76
+ name: ScannedPlatform;
77
+ /**
78
+ * The version spelled in `@available` (`17.0` in `@available(iOS 17.0, *)`), or absent when no
79
+ * attribute on the declaration or its enclosing types names one. The latest version wins when
80
+ * several do.
81
+ */
82
+ introduced?: string;
83
+ /**
84
+ * How the declaration's own `@available` attributes deprecate it on this OS, or absent when they
85
+ * don't. Enclosing types are not read: a member of a deprecated type is not itself reported as
86
+ * deprecated.
87
+ */
88
+ deprecated?: ExportedDeprecation;
89
+ }
90
+ /**
91
+ * A deprecation from `@available`: `@available(*, deprecated, ...)` on every OS, or
92
+ * `@available(iOS, deprecated: 16, obsoleted: 18, ...)` on one. Each field is absent when not
93
+ * written. When a platform has its own attribute and a `*` one also applies, they combine and the
94
+ * platform's fields win.
95
+ */
96
+ export interface ExportedDeprecation {
97
+ /** The version from `deprecated: 16`; absent for a bare `deprecated`. */
98
+ since?: string;
99
+ /**
100
+ * The version from `obsoleted: 18`, from which the declaration is no longer available. A
101
+ * declaration that is only obsoleted is still reported as deprecated.
102
+ */
103
+ obsoleted?: string;
104
+ /** The `message:` text. */
105
+ message?: string;
106
+ /**
107
+ * The `renamed:` text: the Swift name of the replacement, as written (`newName`,
108
+ * `other(value:)`). It is not resolved to a JS name.
109
+ */
110
+ renamed?: string;
111
+ }
112
+ /**
113
+ * The parts of a declaration or member that say where and to whom it is available. A declaration no
114
+ * platform builds is not reported, so `platforms` is never empty.
115
+ */
116
+ export interface ExportedAvailability {
117
+ /** The OSes that build it: its `#if` conditions hold and no `@available` makes it unavailable. */
118
+ platforms: ExportedPlatform[];
119
+ }
120
+ /** The spelled Swift access modifier of a declaration. */
121
+ export interface ExportedAccess {
122
+ /**
123
+ * `open`, `public`, `package`, `internal`, `fileprivate`, or `private`, or absent when none is
124
+ * written. A setter-only modifier like `private(set)` is not reported.
125
+ */
126
+ accessLevel?: string;
127
+ }
69
128
  /** One parameter of a `@JS` function or `@JS init`. */
70
129
  export interface ExportedParameter {
71
130
  /** The argument label, or `_` when unlabeled. */
@@ -75,9 +134,11 @@ export interface ExportedParameter {
75
134
  type: TypeNode;
76
135
  /** True when the caller may omit it: a default value or an optional type. */
77
136
  optional: boolean;
137
+ /** The default value as Swift source text (`1`, `"x"`, `.fast`), absent when none is written. */
138
+ defaultValue?: string;
78
139
  }
79
140
  /** One `@JS func` on a module or shared object. */
80
- export interface ExportedFunction {
141
+ export interface ExportedFunction extends ExportedAccess, ExportedAvailability {
81
142
  name: string;
82
143
  /** The JS name it binds under: the `@JS("x")` override, else `name`. */
83
144
  jsName: string;
@@ -89,25 +150,29 @@ export interface ExportedFunction {
89
150
  static: boolean;
90
151
  }
91
152
  /** One `@JS var` on a module or shared object. */
92
- export interface ExportedProperty {
153
+ export interface ExportedProperty extends ExportedAccess, ExportedAvailability {
93
154
  name: string;
94
155
  jsName: string;
95
156
  /** Absent when the type isn't determinable syntactically; the macro binds it getter-only. */
96
157
  type?: TypeNode;
97
158
  readonly: boolean;
98
159
  static: boolean;
160
+ /** The initial value of a stored property as Swift source text, absent when none is written. */
161
+ defaultValue?: string;
99
162
  }
100
163
  /** One `@Record` property: a data slot, not a JS accessor. */
101
- export interface ExportedRecordProperty {
164
+ export interface ExportedRecordProperty extends ExportedAccess, ExportedAvailability {
102
165
  name: string;
103
166
  type: TypeNode;
104
167
  /** Optional-typed. */
105
168
  optional: boolean;
106
169
  /** Whether JS must supply it: neither defaulted nor optional. */
107
170
  required: boolean;
171
+ /** The default value as Swift source text, absent when none is written. */
172
+ defaultValue?: string;
108
173
  }
109
174
  /** An `@ExpoModule` type and its `@JS` surface. */
110
- export interface ExportedModule {
175
+ export interface ExportedModule extends ExportedAccess, ExportedAvailability {
111
176
  /** The Swift class name. A module is always declared at file scope. */
112
177
  name: string;
113
178
  /** The JS module name: `@ExpoModule("Foo")` override, else the class name. */
@@ -139,7 +204,7 @@ export interface ExportedClass {
139
204
  jsName?: string;
140
205
  }
141
206
  /** One `@Event var`: a typed event JS listens for by name, rather than calls. */
142
- export interface ExportedEvent {
207
+ export interface ExportedEvent extends ExportedAccess, ExportedAvailability {
143
208
  /** The Swift property name, e.g. `onStatusChange`. */
144
209
  name: string;
145
210
  /**
@@ -152,8 +217,12 @@ export interface ExportedEvent {
152
217
  /** `@Event(sync: true)`, dispatching inline on the JS thread instead of scheduling. */
153
218
  sync: boolean;
154
219
  }
220
+ /** The `@JS init` of a shared object: the constructor JS calls with `new`. */
221
+ export interface ExportedInitializer extends ExportedAccess, ExportedAvailability {
222
+ parameters: ExportedParameter[];
223
+ }
155
224
  /** A `@SharedObject` type: a JS class with an optional constructor plus its `@JS` members. */
156
- export interface ExportedSharedObject {
225
+ export interface ExportedSharedObject extends ExportedAccess, ExportedAvailability {
157
226
  /** The Swift class name, qualified with the types it is nested in (`Outer.Player`). */
158
227
  name: string;
159
228
  /**
@@ -161,15 +230,18 @@ export interface ExportedSharedObject {
161
230
  * types.
162
231
  */
163
232
  jsName: string;
164
- /** The `@JS init` parameters, or absent when there's none. At most one constructor. */
165
- constructorParameters?: ExportedParameter[];
233
+ /**
234
+ * The `@JS init`, or absent when there's none. At most one constructor. Not named `constructor`,
235
+ * which every JS object inherits.
236
+ */
237
+ initializer?: ExportedInitializer;
166
238
  functions: ExportedFunction[];
167
239
  properties: ExportedProperty[];
168
240
  events: ExportedEvent[];
169
241
  file: string;
170
242
  }
171
243
  /** A `@Record` type and its properties. */
172
- export interface ExportedRecord {
244
+ export interface ExportedRecord extends ExportedAccess, ExportedAvailability {
173
245
  /** The Swift type name, qualified with the types it is nested in (`Outer.Options`). */
174
246
  name: string;
175
247
  properties: ExportedRecordProperty[];
@@ -186,7 +258,7 @@ export interface ExportedRecord {
186
258
  * value (`case a = 1; case b` makes `b` 2), and that carry is yours to apply.
187
259
  * - no raw type: always absent, since the enum has no raw values.
188
260
  */
189
- export interface ExportedEnumCase {
261
+ export interface ExportedEnumCase extends ExportedAvailability {
190
262
  /** The case name as declared. */
191
263
  name: string;
192
264
  /** The raw value, decoded for a string and verbatim source text otherwise, or absent per the rule above. */
@@ -196,7 +268,7 @@ export interface ExportedEnumCase {
196
268
  * An `Enumerable` enum: a type crossing the boundary as its raw value rather than as an object.
197
269
  * Detected by conformance, not by a macro attribute, so it carries no `jsName`.
198
270
  */
199
- export interface ExportedEnum {
271
+ export interface ExportedEnum extends ExportedAccess, ExportedAvailability {
200
272
  /** The Swift enum name, qualified with the types it is nested in (`Options.Encoding`). */
201
273
  name: string;
202
274
  /** The raw value type as written, absent for a bare `Enumerable` conformance with no raw type. */
@@ -208,7 +280,7 @@ export interface ExportedEnum {
208
280
  * One alternative a `@Union` may hold. Not a member in the sense a module or shared object has members
209
281
  * (functions, properties, events).
210
282
  */
211
- export interface ExportedUnionMember {
283
+ export interface ExportedUnionMember extends ExportedAvailability {
212
284
  /** The Swift case name. Swift-side only: discrimination is structural, so it never reaches JS. */
213
285
  name: string;
214
286
  /** The associated value's type: what this alternative decodes from. */
@@ -221,7 +293,7 @@ export interface ExportedUnionMember {
221
293
  * succeeds, so where two shapes overlap (`Int` and `Double`, two compatible records) the earlier one
222
294
  * wins. Reordering them describes a different union than the one the module runs.
223
295
  */
224
- export interface ExportedUnion {
296
+ export interface ExportedUnion extends ExportedAccess, ExportedAvailability {
225
297
  /** The Swift enum name, qualified with the types it is nested in (`Options.Value`). */
226
298
  name: string;
227
299
  members: ExportedUnionMember[];
@@ -250,11 +322,6 @@ export interface ScanStats {
250
322
  /** Wall-clock duration of the scan, in milliseconds. */
251
323
  durationMs: number;
252
324
  }
253
- /**
254
- * An Apple OS the scanner attributes modules to, spelled as `os(...)` spells it. The casing is part
255
- * of the output contract, so consumers with a lowercase convention must fold the case themselves.
256
- */
257
- export type ScannedPlatform = 'iOS' | 'macOS' | 'tvOS' | 'watchOS' | 'visionOS';
258
325
  /** One module in the `scan-modules` output. */
259
326
  export interface ScannedModule {
260
327
  name: string;
@@ -292,4 +359,4 @@ export interface ScanExportsResult {
292
359
  * as a clear error instead of silently misread fields.
293
360
  */
294
361
  export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
295
- export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 7;
362
+ export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 8;
package/build/types.js CHANGED
@@ -12,4 +12,4 @@ exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_S
12
12
  * as a clear error instead of silently misread fields.
13
13
  */
14
14
  exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
15
- exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 7;
15
+ exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 8;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "expo-modules-macros",
3
- "version": "0.19.1",
3
+ "version": "0.21.0",
4
4
  "description": "Swift macro plugin for Expo modules",
5
5
  "main": "build/index.js",
6
6
  "types": "build/index.d.ts",
@@ -23,7 +23,9 @@
23
23
  "typescript": "^5.4.0"
24
24
  },
25
25
  "optionalDependencies": {
26
- "@expo/modules-macros-win32-arm64": "0.19.1",
27
- "@expo/modules-macros-win32-x64": "0.19.1"
26
+ "@expo/modules-macros-linux-arm64": "0.21.0",
27
+ "@expo/modules-macros-linux-x64": "0.21.0",
28
+ "@expo/modules-macros-win32-arm64": "0.21.0",
29
+ "@expo/modules-macros-win32-x64": "0.21.0"
28
30
  }
29
31
  }