@barefootjs/jsx 0.38.0 → 0.39.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.
Files changed (87) hide show
  1. package/dist/action-accessor.d.ts +159 -0
  2. package/dist/action-accessor.d.ts.map +1 -0
  3. package/dist/adapters/jsx-adapter.d.ts.map +1 -1
  4. package/dist/analyzer.d.ts +30 -1
  5. package/dist/analyzer.d.ts.map +1 -1
  6. package/dist/async-action-refusal.d.ts +45 -0
  7. package/dist/async-action-refusal.d.ts.map +1 -0
  8. package/dist/compiler.d.ts.map +1 -1
  9. package/dist/debug.d.ts +61 -5
  10. package/dist/debug.d.ts.map +1 -1
  11. package/dist/errors.d.ts +4 -0
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/format-date-refusal.d.ts +2 -6
  14. package/dist/format-date-refusal.d.ts.map +1 -1
  15. package/dist/index.d.ts +2 -2
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1056 -344
  18. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  19. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  20. package/dist/ir-to-client-js/compute-inlinability.d.ts.map +1 -1
  21. package/dist/ir-to-client-js/compute-scope.d.ts.map +1 -1
  22. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts +2 -0
  23. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts.map +1 -1
  24. package/dist/ir-to-client-js/csr-substitute.d.ts.map +1 -1
  25. package/dist/ir-to-client-js/declaration-sort.d.ts +2 -1
  26. package/dist/ir-to-client-js/declaration-sort.d.ts.map +1 -1
  27. package/dist/ir-to-client-js/emit-module-level.d.ts.map +1 -1
  28. package/dist/ir-to-client-js/emit-registration.d.ts.map +1 -1
  29. package/dist/ir-to-client-js/plan/declaration-emit.d.ts +7 -5
  30. package/dist/ir-to-client-js/plan/declaration-emit.d.ts.map +1 -1
  31. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  33. package/dist/ir-to-client-js/types.d.ts +4 -0
  34. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  35. package/dist/ir-to-client-js/utils.d.ts +41 -2
  36. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  37. package/dist/jsx-to-ir.d.ts.map +1 -1
  38. package/dist/signal-initializer.d.ts +24 -0
  39. package/dist/signal-initializer.d.ts.map +1 -0
  40. package/dist/template-position-walk.d.ts +68 -0
  41. package/dist/template-position-walk.d.ts.map +1 -0
  42. package/dist/types.d.ts +51 -0
  43. package/dist/types.d.ts.map +1 -1
  44. package/package.json +2 -2
  45. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +191 -1
  46. package/src/__tests__/action-accessor.test.ts +166 -0
  47. package/src/__tests__/create-mutation.test.ts +220 -0
  48. package/src/__tests__/create-query.test.ts +644 -0
  49. package/src/__tests__/csr-fragment-root-scope-shape.test.ts +156 -0
  50. package/src/__tests__/debug.test.ts +222 -0
  51. package/src/__tests__/doc-examples.test.ts +66 -3
  52. package/src/__tests__/props-destructuring.test.ts +79 -4
  53. package/src/__tests__/reactive-factory-arity.test.ts +311 -0
  54. package/src/__tests__/ssr-portal-ref-callback.test.ts +5 -3
  55. package/src/action-accessor.ts +289 -0
  56. package/src/adapters/jsx-adapter.ts +17 -0
  57. package/src/analyzer.ts +558 -33
  58. package/src/async-action-refusal.ts +254 -0
  59. package/src/compiler.ts +3 -0
  60. package/src/debug.ts +318 -103
  61. package/src/errors.ts +39 -0
  62. package/src/format-date-refusal.ts +6 -125
  63. package/src/index.ts +2 -1
  64. package/src/ir-to-client-js/build-references.ts +6 -2
  65. package/src/ir-to-client-js/collect-elements.ts +1 -0
  66. package/src/ir-to-client-js/compute-inlinability.ts +2 -1
  67. package/src/ir-to-client-js/compute-scope.ts +3 -1
  68. package/src/ir-to-client-js/control-flow/plan/build-insert.ts +1 -0
  69. package/src/ir-to-client-js/control-flow/plan/insert.ts +2 -0
  70. package/src/ir-to-client-js/control-flow/stringify/insert.ts +1 -1
  71. package/src/ir-to-client-js/csr-substitute.ts +11 -3
  72. package/src/ir-to-client-js/declaration-sort.ts +7 -3
  73. package/src/ir-to-client-js/emit-module-level.ts +7 -4
  74. package/src/ir-to-client-js/emit-registration.ts +5 -10
  75. package/src/ir-to-client-js/index.ts +7 -2
  76. package/src/ir-to-client-js/phases/ref-callbacks.ts +1 -1
  77. package/src/ir-to-client-js/plan/build-declaration-emit.ts +16 -15
  78. package/src/ir-to-client-js/plan/declaration-emit.ts +7 -5
  79. package/src/ir-to-client-js/prop-handling.ts +4 -0
  80. package/src/ir-to-client-js/reactivity.ts +1 -0
  81. package/src/ir-to-client-js/stringify/declaration-emit.ts +14 -7
  82. package/src/ir-to-client-js/types.ts +4 -0
  83. package/src/ir-to-client-js/utils.ts +55 -7
  84. package/src/jsx-to-ir.ts +36 -2
  85. package/src/signal-initializer.ts +36 -0
  86. package/src/template-position-walk.ts +203 -0
  87. package/src/types.ts +52 -0
package/src/analyzer.ts CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  import ts from 'typescript'
10
10
  import { CLIENT_DIRECTIVE_INTERIOR_RE, USE_CLIENT_DIRECTIVE, isUseClientDirectiveText } from './directives.ts'
11
- import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation } from './types.ts'
11
+ import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation, SignalFactoryCall } from './types.ts'
12
12
  import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr, tsNodeToParsedExpr } from './expression-parser.ts'
13
13
  import type { CallbackBodyAcceptor } from './adapters/interface.ts'
14
14
  import { rewriteBarePropRefs } from './prop-rewrite.ts'
@@ -31,6 +31,7 @@ import { baseTypeName } from './rich-type-evidence.ts'
31
31
  import { CATALOGUED_RICH_TYPE_NAMES } from './date-lowering.ts'
32
32
  import path from 'node:path'
33
33
  import fs from 'node:fs'
34
+ import { signalSecondBinding } from './signal-initializer.ts'
34
35
 
35
36
  // =============================================================================
36
37
  // TypeScript Program Creation
@@ -96,14 +97,29 @@ function findBrandPackageImportLoc(
96
97
  * imported types may resolve to `any` and the signal/memo regex fallback kicks in.
97
98
  * For full type resolution in build tools, pass a pre-built ts.Program via
98
99
  * CompileOptions.program instead.
100
+ *
101
+ * `hostOptions.currentDirectory` pins the directory a RELATIVE `filePath`
102
+ * (and the Program's own `getCurrentDirectory()`, which also roots
103
+ * `@types` discovery) resolves against, instead of `process.cwd()`. The
104
+ * Program still serves `source` at the relative name, so
105
+ * `program.getSourceFile(filePath)` resolves to it and the result can be
106
+ * handed to `compileJSX` as `CompileOptions.program` under that same
107
+ * relative `filePath`. Used by the conformance harness
108
+ * (`packages/adapter-tests/src/harness-program.ts`) to compile fixtures
109
+ * under a relative virtual name without its type resolution depending on
110
+ * where the process was started (#3220). Omitted, behaviour is unchanged.
99
111
  */
100
112
  export function createProgramForFile(
101
113
  source: string,
102
- filePath: string
114
+ filePath: string,
115
+ hostOptions: { currentDirectory?: string } = {}
103
116
  ): { program: ts.Program; sourceFile: ts.SourceFile; checker: ts.TypeChecker } | null {
104
117
  incrementCounter('programCreations')
105
118
  try {
106
- const normalizedPath = path.resolve(filePath)
119
+ const { currentDirectory } = hostOptions
120
+ const resolveFrom = (fileName: string): string =>
121
+ currentDirectory === undefined ? path.resolve(fileName) : path.resolve(currentDirectory, fileName)
122
+ const normalizedPath = resolveFrom(filePath)
107
123
 
108
124
  const compilerOptions: ts.CompilerOptions = {
109
125
  target: ts.ScriptTarget.Latest,
@@ -120,18 +136,19 @@ export function createProgramForFile(
120
136
 
121
137
  const virtualHost: ts.CompilerHost = {
122
138
  ...defaultHost,
139
+ ...(currentDirectory === undefined ? {} : { getCurrentDirectory: () => currentDirectory }),
123
140
  getSourceFile(fileName, languageVersion) {
124
- if (path.resolve(fileName) === normalizedPath) {
141
+ if (resolveFrom(fileName) === normalizedPath) {
125
142
  return ts.createSourceFile(fileName, source, languageVersion, true, ts.ScriptKind.TSX)
126
143
  }
127
144
  return defaultHost.getSourceFile(fileName, languageVersion)
128
145
  },
129
146
  fileExists(fileName) {
130
- if (path.resolve(fileName) === normalizedPath) return true
147
+ if (resolveFrom(fileName) === normalizedPath) return true
131
148
  return defaultHost.fileExists(fileName)
132
149
  },
133
150
  readFile(fileName) {
134
- if (path.resolve(fileName) === normalizedPath) return source
151
+ if (resolveFrom(fileName) === normalizedPath) return source
135
152
  return defaultHost.readFile(fileName)
136
153
  },
137
154
  }
@@ -148,6 +165,26 @@ export function createProgramForFile(
148
165
  }
149
166
  }
150
167
 
168
+ /**
169
+ * The Program to pass as `compileJSX`'s `program` when a test harness
170
+ * compiles `source` under the relative virtual `filename`, with type
171
+ * resolution anchored at `anchorDir` instead of `process.cwd()` — or
172
+ * `undefined` when the compiler would not build a checker for this source.
173
+ *
174
+ * Without it, a harness compile resolves `@barefootjs/*` relative to the
175
+ * directory `bun test` was started from, so a `Reactive<T>` accessor read
176
+ * such as `fetchPosts.isPending()` is typed `any` from the repo root and
177
+ * its real type from a package (#3220). `anchorDir` need not exist: module
178
+ * resolution only probes its ancestors for `node_modules`. The one
179
+ * implementation for every harness that compiles under relative names:
180
+ * the conformance harness (`packages/adapter-tests/src/harness-program.ts`)
181
+ * and the docs-example suite (`doc-examples.test.ts`).
182
+ */
183
+ export function createAnchoredProgram(source: string, filename: string, anchorDir: string): ts.Program | undefined {
184
+ if (!needsTypeBasedDetection(source)) return undefined
185
+ return createProgramForFile(source, filename, { currentDirectory: anchorDir })?.program
186
+ }
187
+
151
188
  // =============================================================================
152
189
  // Main Entry Point
153
190
  // =============================================================================
@@ -1142,6 +1179,22 @@ const PRIMITIVE_CANONICAL_NAMES: Record<string, 'signal' | 'memo' | 'effect' | '
1142
1179
  // is recorded separately on the collected signal so adapters can lower the
1143
1180
  // reader value; the reactivity kind itself is just `signal`.
1144
1181
  createSearchParams: 'signal',
1182
+ // Async reactive factories (#3165) return a `[value, action]` tuple whose
1183
+ // value half is a signal getter, so they resolve to the `signal` kind too;
1184
+ // SIGNAL_FACTORY_KINDS below records which factory it was.
1185
+ createQuery: 'signal',
1186
+ createMutation: 'signal',
1187
+ }
1188
+
1189
+ /**
1190
+ * Async reactive factories → their `SignalFactoryCall` kind (#3165). The value
1191
+ * half of the tuple is collected as a signal seeded from `options.initial`;
1192
+ * the kind tells every backend that re-emits the declaration to call the
1193
+ * factory instead of `createSignal`.
1194
+ */
1195
+ const SIGNAL_FACTORY_KINDS: Record<string, SignalFactoryCall['kind']> = {
1196
+ createQuery: 'query',
1197
+ createMutation: 'mutation',
1145
1198
  }
1146
1199
 
1147
1200
  /**
@@ -1271,15 +1324,41 @@ function resolveEnvSignalKey(
1271
1324
  callExpr: ts.CallExpression,
1272
1325
  ctx: AnalyzerContext
1273
1326
  ): string | null {
1327
+ return resolveClientFactoryEntry(callExpr, ENV_SIGNAL_FACTORIES, ctx)
1328
+ }
1329
+
1330
+ /**
1331
+ * Resolve a call expression to the {@link SIGNAL_FACTORY_KINDS} kind of the
1332
+ * async reactive factory it calls (`createQuery(...)` → `'query'`), or null.
1333
+ * Same fast/slow paths as {@link resolveEnvSignalKey}.
1334
+ */
1335
+ function resolveSignalFactoryKind(
1336
+ callExpr: ts.CallExpression,
1337
+ ctx: AnalyzerContext
1338
+ ): SignalFactoryCall['kind'] | null {
1339
+ return resolveClientFactoryEntry(callExpr, SIGNAL_FACTORY_KINDS, ctx)
1340
+ }
1341
+
1342
+ /**
1343
+ * Look a call's callee up in a table keyed by `@barefootjs/client` export
1344
+ * names: the direct name, an alias resolved through the checker, or a
1345
+ * `bf.<name>` namespace access. Shared by the env-signal and async-factory
1346
+ * resolvers above.
1347
+ */
1348
+ function resolveClientFactoryEntry<T>(
1349
+ callExpr: ts.CallExpression,
1350
+ table: Record<string, T>,
1351
+ ctx: AnalyzerContext
1352
+ ): T | null {
1274
1353
  if (ts.isIdentifier(callExpr.expression)) {
1275
- const key = ENV_SIGNAL_FACTORIES[callExpr.expression.text]
1276
- if (key) return key
1354
+ const hit = table[callExpr.expression.text]
1355
+ if (hit) return hit
1277
1356
  const canonical = resolveCanonicalClientExportName(callExpr.expression, ctx)
1278
- return canonical ? (ENV_SIGNAL_FACTORIES[canonical] ?? null) : null
1357
+ return canonical ? (table[canonical] ?? null) : null
1279
1358
  }
1280
1359
  if (ts.isPropertyAccessExpression(callExpr.expression)) {
1281
- const key = ENV_SIGNAL_FACTORIES[callExpr.expression.name.text]
1282
- if (key && isBarefootClientNamespace(callExpr.expression.expression, ctx)) return key
1360
+ const hit = table[callExpr.expression.name.text]
1361
+ if (hit && isBarefootClientNamespace(callExpr.expression.expression, ctx)) return hit
1283
1362
  }
1284
1363
  return null
1285
1364
  }
@@ -1323,6 +1402,11 @@ function isSignalDeclaration(node: ts.VariableDeclaration, ctx: AnalyzerContext)
1323
1402
  function collectSignal(node: ts.VariableDeclaration, ctx: AnalyzerContext): void {
1324
1403
  const pattern = node.name as ts.ArrayBindingPattern
1325
1404
  const callExpr = node.initializer as ts.CallExpression
1405
+ const factoryKind = resolveSignalFactoryKind(callExpr, ctx)
1406
+ if (factoryKind) {
1407
+ collectFactorySignal(node, pattern, callExpr, factoryKind, ctx)
1408
+ return
1409
+ }
1326
1410
 
1327
1411
  const elements = pattern.elements
1328
1412
  // Getter-elided form: `const [, setActive] = createSignal(0)`. The first
@@ -1408,6 +1492,137 @@ function collectSignal(node: ts.VariableDeclaration, ctx: AnalyzerContext): void
1408
1492
  })
1409
1493
  }
1410
1494
 
1495
+ /**
1496
+ * Collect `const [value, action] = createQuery(fn, options)` (#3165) or
1497
+ * `createMutation(fn, options)` (#3210) as a signal whose getter is the value
1498
+ * and whose initial value is `options.initial` (a query) or `undefined` (a
1499
+ * mutation, which has no `initial`: spec/async.md §7.4). The action is
1500
+ * recorded on `factory`, never as a setter, so setter-keyed logic
1501
+ * (controlled-prop sync, handler→setter wiring, SSR setter stubs) leaves it
1502
+ * alone.
1503
+ *
1504
+ * `initial` is read structurally from an object-literal `options` with no
1505
+ * spread: its value expression when the key is present, the literal
1506
+ * `undefined` when it isn't. Any other `options`
1507
+ * shape seeds from the member read `(<options>).initial`, which each backend
1508
+ * lowers or refuses like any other expression — never a guess.
1509
+ */
1510
+ function collectFactorySignal(
1511
+ node: ts.VariableDeclaration,
1512
+ pattern: ts.ArrayBindingPattern,
1513
+ callExpr: ts.CallExpression,
1514
+ kind: SignalFactoryCall['kind'],
1515
+ ctx: AnalyzerContext,
1516
+ ): void {
1517
+ const elements = pattern.elements
1518
+ const bindingName = (el: ts.ArrayBindingElement | undefined): string | null =>
1519
+ el && ts.isBindingElement(el) && ts.isIdentifier(el.name) ? el.name.text : null
1520
+ // BF115 reports any other destructure shape; nothing is collected for it.
1521
+ if (elements.length < 1 || elements.length > 2) return
1522
+ const getterElided = ts.isOmittedExpression(elements[0])
1523
+ const valueName = getterElided ? null : bindingName(elements[0])
1524
+ if (!getterElided && valueName === null) return
1525
+ const action = elements.length === 2 ? bindingName(elements[1]) : null
1526
+ if (elements.length === 2 && action === null) return
1527
+ if (getterElided && action === null) return
1528
+
1529
+ // A mutation's value is `undefined` until its action is called; an
1530
+ // `initial` it was given anyway is refused (BF118), never read.
1531
+ const initialNode: FactoryInitialNode = kind === 'mutation'
1532
+ ? { kind: 'absent' }
1533
+ : factoryInitialNode(callExpr.arguments[1])
1534
+ const initialValue = initialNode.kind === 'expression'
1535
+ ? ctx.getJS(initialNode.node)
1536
+ : initialNode.kind === 'member-read'
1537
+ ? `(${ctx.getJS(initialNode.options)}).initial`
1538
+ : 'undefined'
1539
+ const typedInitialValue = initialNode.kind === 'expression'
1540
+ ? initialNode.node.getText(ctx.sourceFile)
1541
+ : initialNode.kind === 'member-read'
1542
+ ? `(${initialNode.options.getText(ctx.sourceFile)}).initial`
1543
+ : undefined
1544
+ const initialFreeIdentifiers = initialNode.kind === 'expression'
1545
+ ? extractFreeIdentifiersFromNode(initialNode.node)
1546
+ : initialNode.kind === 'member-read'
1547
+ ? extractFreeIdentifiersFromNode(initialNode.options)
1548
+ : new Set<string>()
1549
+
1550
+ let type: TypeInfo = { kind: 'unknown', raw: 'unknown' }
1551
+ if (callExpr.typeArguments && callExpr.typeArguments.length > 0) {
1552
+ type = typeNodeToTypeInfo(callExpr.typeArguments[0], ctx.sourceFile) ?? type
1553
+ } else if (initialNode.kind !== 'absent') {
1554
+ type = inferTypeFromValue(initialValue)
1555
+ }
1556
+
1557
+ // Destructured-arg components (#2265): the CSR `template:` arrow's
1558
+ // module-scope fallback needs `_p.<name>` for a bare destructured prop in
1559
+ // `initial`, same as a `createSignal` initial value.
1560
+ let templateInitialValue: string | undefined
1561
+ if (!ctx.propsObjectName && initialNode.kind === 'expression') {
1562
+ const propNames = new Set(ctx.propsParams.map(p => p.name))
1563
+ if (propNames.size > 0) {
1564
+ const propAliases = buildPropAliasMap(ctx.propsParams)
1565
+ templateInitialValue = rewriteBarePropRefs(initialValue, initialNode.node, propNames, undefined, propAliases)
1566
+ }
1567
+ }
1568
+
1569
+ const argTexts = callExpr.arguments.map(arg => ctx.getJS(arg))
1570
+ const requestArg = callExpr.arguments[0]
1571
+
1572
+ ctx.signals.push({
1573
+ getter: valueName ?? `__bfGet_${action}`,
1574
+ setter: null,
1575
+ getterElided: getterElided || undefined,
1576
+ initialValue,
1577
+ typedInitialValue: typedInitialValue !== undefined && typedInitialValue !== initialValue ? typedInitialValue : undefined,
1578
+ templateInitialValue,
1579
+ type,
1580
+ loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
1581
+ initialFreeIdentifiers,
1582
+ factory: {
1583
+ kind,
1584
+ callee: callExpr.expression.getText(ctx.sourceFile),
1585
+ argsText: argTexts.join(', '),
1586
+ requestText: argTexts[0] ?? '',
1587
+ requestFreeIdentifiers: requestArg ? extractFreeIdentifiersFromNode(requestArg) : new Set(),
1588
+ action,
1589
+ },
1590
+ })
1591
+ }
1592
+
1593
+ /**
1594
+ * Where an async factory's `initial` comes from (#3165): the `initial`
1595
+ * property's value in an object-literal `options` (`expression`), nothing
1596
+ * (`absent` — no `options`, or a literal without the key), or a member read
1597
+ * of `options` itself when the literal can't be read structurally (spread,
1598
+ * computed key, accessor) or `options` isn't a literal at all (`member-read`).
1599
+ */
1600
+ type FactoryInitialNode =
1601
+ | { kind: 'expression'; node: ts.Expression }
1602
+ | { kind: 'absent' }
1603
+ | { kind: 'member-read'; options: ts.Expression }
1604
+
1605
+ function factoryInitialNode(options: ts.Expression | undefined): FactoryInitialNode {
1606
+ if (!options) return { kind: 'absent' }
1607
+ let unwrapped: ts.Expression = options
1608
+ while (ts.isParenthesizedExpression(unwrapped) || ts.isAsExpression(unwrapped) || ts.isSatisfiesExpression(unwrapped)) {
1609
+ unwrapped = unwrapped.expression
1610
+ }
1611
+ if (!ts.isObjectLiteralExpression(unwrapped)) return { kind: 'member-read', options }
1612
+ let found: ts.Expression | null = null
1613
+ for (const prop of unwrapped.properties) {
1614
+ if (ts.isSpreadAssignment(prop)) return { kind: 'member-read', options }
1615
+ const name = prop.name
1616
+ if (name === undefined || ts.isComputedPropertyName(name)) return { kind: 'member-read', options }
1617
+ const key = ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name) ? name.text : null
1618
+ if (key !== 'initial') continue
1619
+ if (ts.isPropertyAssignment(prop)) found = prop.initializer
1620
+ else if (ts.isShorthandPropertyAssignment(prop)) found = prop.name
1621
+ else return { kind: 'member-read', options }
1622
+ }
1623
+ return found ? { kind: 'expression', node: found } : { kind: 'absent' }
1624
+ }
1625
+
1411
1626
  /**
1412
1627
  * Detects `const s = createSignal(...)` — the tuple is stored in an
1413
1628
  * Identifier rather than destructured. The accessor(s) appear in later
@@ -2138,6 +2353,10 @@ const CLIENT_EXPORTS = new Set([
2138
2353
  // getter; the compiler lowers the reader value per adapter via the signal's
2139
2354
  // `envReader` key, with no `searchParams`-name allow-list.
2140
2355
  'createSearchParams',
2356
+ // Async layer 0 (spec/async.md §7): `http` descriptors and `HttpError`
2357
+ // (#3161), and `createQuery` (#3165) / `createMutation` (#3210),
2358
+ // recognised structurally as factory signals.
2359
+ 'http', 'HttpError', 'createQuery', 'createMutation',
2141
2360
  // Pure URL-query builder (#2042) — the functional counterpart to
2142
2361
  // `searchParams`. Runs natively on the client; SSR adapters lower a
2143
2362
  // `queryHref(base, { … })` call to their query helper (go-template: `bf_query`).
@@ -2875,6 +3094,7 @@ function collectFunction(
2875
3094
  declarationKind: 'function',
2876
3095
  isModule: _isModule || undefined,
2877
3096
  isJsxFunction: isJsxFunction || undefined,
3097
+ freeIdentifiers: extractFreeIdentifiersFromNode(node),
2878
3098
  loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
2879
3099
  })
2880
3100
  }
@@ -3428,6 +3648,12 @@ function collectConstant(
3428
3648
 
3429
3649
  // Compute AST-derived flags for Phase 2 optimization
3430
3650
  const containsArrow = node.initializer ? nodeContainsArrow(node.initializer) : false
3651
+ let unwrappedInitializer: ts.Expression | undefined = node.initializer
3652
+ while (unwrappedInitializer && (ts.isParenthesizedExpression(unwrappedInitializer) || ts.isAsExpression(unwrappedInitializer) || ts.isSatisfiesExpression(unwrappedInitializer))) {
3653
+ unwrappedInitializer = unwrappedInitializer.expression
3654
+ }
3655
+ const isFunctionValue = unwrappedInitializer !== undefined &&
3656
+ (ts.isArrowFunction(unwrappedInitializer) || ts.isFunctionExpression(unwrappedInitializer))
3431
3657
  const systemConstructKind = node.initializer ? getSystemConstructKind(node.initializer) : undefined
3432
3658
 
3433
3659
  // Pre-transform bare prop refs for template inlining (#807). Two
@@ -3472,7 +3698,8 @@ function collectConstant(
3472
3698
  const shadowedByNonAlias = new Set<string>()
3473
3699
  for (const s of ctx.signals) {
3474
3700
  shadowedByNonAlias.add(s.getter)
3475
- if (s.setter) shadowedByNonAlias.add(s.setter)
3701
+ const second = signalSecondBinding(s)
3702
+ if (second) shadowedByNonAlias.add(second)
3476
3703
  }
3477
3704
  for (const m of ctx.memos) shadowedByNonAlias.add(m.name)
3478
3705
  const aliases = new Set<string>()
@@ -3536,6 +3763,7 @@ function collectConstant(
3536
3763
  isJsx,
3537
3764
  isJsxFunction: isJsxFunction || undefined,
3538
3765
  containsArrow: containsArrow || undefined,
3766
+ isFunctionValue: isFunctionValue || undefined,
3539
3767
  systemConstructKind,
3540
3768
  templateValue,
3541
3769
  origin: {
@@ -3703,7 +3931,10 @@ function collectKeysFromMembers(
3703
3931
  *
3704
3932
  * `array`/`object` admit only when EVERY reachable leaf resolves — an
3705
3933
  * array's element type and an object's every property type must pass this
3706
- * same check, recursively. A union, a function, or an un-catalogued named
3934
+ * same check, recursively. A same-file object type referenced by name
3935
+ * (`Item` in `items: Item[]`) is checked through its declaration's members
3936
+ * (`LocalObjectMemberTypes`) the same way an inline object literal's are.
3937
+ * A union, a function, or any other named
3707
3938
  * type reachable ANYWHERE inside the shape declines the WHOLE member (not
3708
3939
  * just that one leaf): `collectMemberTypes` is an all-or-nothing gate per
3709
3940
  * member, so a partially-resolvable structural type must still decline —
@@ -3728,22 +3959,91 @@ function collectKeysFromMembers(
3728
3959
  * synthesized struct is exactly as faithful a representation as the type
3729
3960
  * itself claims, nothing is being guessed.
3730
3961
  */
3731
- function isResolvableMemberType(info: TypeInfo): boolean {
3962
+ function isResolvableMemberType(
3963
+ info: TypeInfo,
3964
+ localObjectMembers?: LocalObjectMemberTypes,
3965
+ visiting: ReadonlySet<string> = new Set(),
3966
+ ): boolean {
3967
+ const recurse = (t: TypeInfo): boolean => isResolvableMemberType(t, localObjectMembers, visiting)
3732
3968
  switch (info.kind) {
3733
3969
  case 'primitive':
3734
3970
  return info.primitive === 'string' || info.primitive === 'number' || info.primitive === 'boolean'
3735
- case 'interface':
3736
- return CATALOGUED_RICH_TYPE_NAMES.has(baseTypeName(info.raw))
3971
+ case 'interface': {
3972
+ if (CATALOGUED_RICH_TYPE_NAMES.has(baseTypeName(info.raw))) return true
3973
+ // A same-file object type referenced BY NAME (`initial: State`,
3974
+ // `items: Item[]`) is the same structural shape as its inline
3975
+ // spelling — see `LocalObjectMemberTypes`. A name already on the
3976
+ // resolution stack (a recursive type) declines rather than loop.
3977
+ if (!localObjectMembers || visiting.has(info.raw)) return false
3978
+ const members = localObjectMembers(info.raw)
3979
+ if (!members) return false
3980
+ const inner = new Set(visiting).add(info.raw)
3981
+ return members.every(t => isResolvableMemberType(t, localObjectMembers, inner))
3982
+ }
3737
3983
  case 'array':
3738
- return !!info.elementType && isResolvableMemberType(info.elementType)
3984
+ return !!info.elementType && recurse(info.elementType)
3739
3985
  case 'object':
3740
- return info.properties !== undefined && info.properties.every(prop => isResolvableMemberType(prop.type))
3986
+ return info.properties !== undefined && info.properties.every(prop => recurse(prop.type))
3741
3987
  // Unions, functions, and `unknown` all decline — see docstring.
3742
3988
  default:
3743
3989
  return false
3744
3990
  }
3745
3991
  }
3746
3992
 
3993
+ /**
3994
+ * Member types of a same-file, non-generic object type declared by name —
3995
+ * an `interface` with no `extends` clause, or a `type X = { … }` alias —
3996
+ * or `null` when `name` isn't one (an import, a generic, a union alias, an
3997
+ * interface with heritage, or a declaration with a non-property member such
3998
+ * as a method or index signature). #3142 follow-up: `{ initial }: {
3999
+ * initial: State }` declined to `unknown` while the `props`-object form
4000
+ * (`props: { initial: State }`, `extractPropsFromTypeMembers`) resolved
4001
+ * `State` — the same destructured-vs-props-object asymmetry #2677 closed
4002
+ * for INLINE object shapes, left open for NAMED ones. A named same-file
4003
+ * object type is exactly as representable as its inline spelling: it lands
4004
+ * in `ir.metadata.typeDefinitions`, and typed adapters already emit a
4005
+ * struct for it (go-template's `typeDefinitionToGo`), so admitting it
4006
+ * resurrects neither #2150 concern.
4007
+ */
4008
+ type LocalObjectMemberTypes = (name: string) => TypeInfo[] | null
4009
+
4010
+ function localObjectMemberTypesFor(ctx: AnalyzerContext): LocalObjectMemberTypes {
4011
+ // Each lookup walks the whole source file, and one props annotation can
4012
+ // reach the same name many times (`Item` from several `Item[]` members),
4013
+ // so answer each name once per annotation.
4014
+ const cache = new Map<string, TypeInfo[] | null>()
4015
+ const lookup = (name: string): TypeInfo[] | null => {
4016
+ // Exactly one declaration, or decline: two `interface State` blocks
4017
+ // merge into one type, and checking either half alone could admit a
4018
+ // shape whose other half carries a member this gate would refuse.
4019
+ const decls = findTypeDeclarations(name, ctx.sourceFile)
4020
+ if (decls.length !== 1) return null
4021
+ const decl = decls[0]
4022
+ if (decl.typeParameters?.length) return null
4023
+ let members: ts.NodeArray<ts.TypeElement>
4024
+ if (ts.isInterfaceDeclaration(decl)) {
4025
+ if (decl.heritageClauses?.length) return null
4026
+ members = decl.members
4027
+ } else if (ts.isTypeLiteralNode(decl.type)) {
4028
+ members = decl.type.members
4029
+ } else {
4030
+ return null
4031
+ }
4032
+ const types: TypeInfo[] = []
4033
+ for (const member of members) {
4034
+ if (!ts.isPropertySignature(member) || !member.type) return null
4035
+ const info = typeNodeToTypeInfo(member.type, ctx.sourceFile)
4036
+ if (!info) return null
4037
+ types.push(info)
4038
+ }
4039
+ return types
4040
+ }
4041
+ return (name) => {
4042
+ if (!cache.has(name)) cache.set(name, lookup(name))
4043
+ return cache.get(name) ?? null
4044
+ }
4045
+ }
4046
+
3747
4047
  /**
3748
4048
  * Build a property-name -> { type, optional } map from a props type
3749
4049
  * annotation, for destructured params (`{ value }: Props`) so they carry the
@@ -3759,9 +4059,10 @@ function isResolvableMemberType(info: TypeInfo): boolean {
3759
4059
  * #2252's nullish-flip machinery supplies the nillable representation
3760
4060
  * exactly where absence is semantically observable (#2259).
3761
4061
  * - A member resolves a type when it is a PRIMITIVE (string/number/boolean),
3762
- * a CATALOGUED rich type (`Date`), or a STRUCTURAL shape (array/object)
3763
- * built entirely out of those, recursively (#2677). Unions, functions, and
3764
- * un-catalogued named types (`Map`, `Set`, …) are left as `unknown` — see
4062
+ * a CATALOGUED rich type (`Date`), or a STRUCTURAL shape (array/object,
4063
+ * inline or a same-file object type referenced by name) built entirely
4064
+ * out of those, recursively (#2677). Unions, functions, and other named
4065
+ * types (imports, generics, `Map`, `Set`, …) are left as `unknown` — see
3765
4066
  * `isResolvableMemberType`'s own docstring for why the structural cases
3766
4067
  * are safe to admit and why those three still are not.
3767
4068
  */
@@ -3769,6 +4070,7 @@ function collectMemberTypes(
3769
4070
  typeNode: ts.TypeNode,
3770
4071
  ctx: AnalyzerContext
3771
4072
  ): Map<string, { type: TypeInfo | null; optional: boolean }> | null {
4073
+ const localObjectMembers = localObjectMemberTypesFor(ctx)
3772
4074
  const fromMembers = (
3773
4075
  members: ts.NodeArray<ts.TypeElement>
3774
4076
  ): Map<string, { type: TypeInfo | null; optional: boolean }> => {
@@ -3777,7 +4079,7 @@ function collectMemberTypes(
3777
4079
  if (ts.isPropertySignature(member) && member.name) {
3778
4080
  const info = member.type ? typeNodeToTypeInfo(member.type, ctx.sourceFile) : null
3779
4081
  map.set(member.name.getText(ctx.sourceFile), {
3780
- type: info && isResolvableMemberType(info) ? info : null,
4082
+ type: info && isResolvableMemberType(info, localObjectMembers) ? info : null,
3781
4083
  optional: !!member.questionToken,
3782
4084
  })
3783
4085
  }
@@ -3857,21 +4159,19 @@ function extractPropsFromTypeMembers(
3857
4159
  }
3858
4160
 
3859
4161
  /**
3860
- * Find a type declaration (interface or type alias) by name in the source file.
4162
+ * Every type declaration (interface or type alias) named `typeName` in the
4163
+ * source file, in source order. More than one means interface declaration
4164
+ * merging (or a name reused in nested scopes).
3861
4165
  */
3862
- function findTypeDeclaration(
4166
+ function findTypeDeclarations(
3863
4167
  typeName: string,
3864
4168
  sourceFile: ts.SourceFile
3865
- ): ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined {
3866
- let result: ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined
4169
+ ): Array<ts.InterfaceDeclaration | ts.TypeAliasDeclaration> {
4170
+ const result: Array<ts.InterfaceDeclaration | ts.TypeAliasDeclaration> = []
3867
4171
 
3868
4172
  function visit(node: ts.Node): void {
3869
- if (ts.isInterfaceDeclaration(node) && node.name.text === typeName) {
3870
- result = node
3871
- return
3872
- }
3873
- if (ts.isTypeAliasDeclaration(node) && node.name.text === typeName) {
3874
- result = node
4173
+ if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) && node.name.text === typeName) {
4174
+ result.push(node)
3875
4175
  return
3876
4176
  }
3877
4177
  ts.forEachChild(node, visit)
@@ -3881,6 +4181,17 @@ function findTypeDeclaration(
3881
4181
  return result
3882
4182
  }
3883
4183
 
4184
+ /**
4185
+ * Find a type declaration (interface or type alias) by name in the source
4186
+ * file — the LAST one when the name is declared more than once.
4187
+ */
4188
+ function findTypeDeclaration(
4189
+ typeName: string,
4190
+ sourceFile: ts.SourceFile
4191
+ ): ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined {
4192
+ return findTypeDeclarations(typeName, sourceFile).at(-1)
4193
+ }
4194
+
3884
4195
  // =============================================================================
3885
4196
  // Helpers
3886
4197
  // =============================================================================
@@ -4048,6 +4359,13 @@ function validateContext(ctx: AnalyzerContext): void {
4048
4359
  // failures before factory inlining landed (#931).
4049
4360
  validateReactiveFactoryCalls(ctx)
4050
4361
 
4362
+ // BF115/BF116: flag a RECOGNISED createSignal/createMemo call used with a
4363
+ // destructure arity or argument count it doesn't support — the gap
4364
+ // validateReactiveFactoryCalls above doesn't cover, since it exists to
4365
+ // validate an unrecognised callee and skips createSignal/createMemo
4366
+ // unconditionally (#3159).
4367
+ validateReactiveFactoryArity(ctx)
4368
+
4051
4369
  // BF013: flag a reactive primitive invoked through a namespace import
4052
4370
  // that the analyzer could not resolve (#2771) — same "silently dropped,
4053
4371
  // ReferenceError at hydrate" failure shape as BF011.
@@ -4370,7 +4688,8 @@ function collectResolvedNames(ctx: AnalyzerContext): Set<string> {
4370
4688
  for (const f of ctx.localFunctions) names.add(f.name)
4371
4689
  for (const s of ctx.signals) {
4372
4690
  names.add(s.getter)
4373
- if (s.setter) names.add(s.setter)
4691
+ const second = signalSecondBinding(s)
4692
+ if (second) names.add(second)
4374
4693
  }
4375
4694
  for (const m of ctx.memos) names.add(m.name)
4376
4695
  for (const p of ctx.propsParams) names.add(p.name)
@@ -6009,6 +6328,9 @@ export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
6009
6328
  // import (`import { createSearchParams as csp }`) is accepted here too,
6010
6329
  // rather than falling through to a spurious BF110.
6011
6330
  if (resolveEnvSignalKey(decl.initializer, ctx)) continue
6331
+ // Async reactive factories (`createQuery`, #3165) return a
6332
+ // `[value, action]` tuple and are collected by `collectFactorySignal`.
6333
+ if (resolveSignalFactoryKind(decl.initializer, ctx)) continue
6012
6334
 
6013
6335
  const declinedEntry = ctx.declinedReactiveFactories.get(callee)
6014
6336
  if (declinedEntry) {
@@ -6064,6 +6386,209 @@ export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
6064
6386
  }
6065
6387
  }
6066
6388
 
6389
+ /**
6390
+ * BF115 / BF116 (#3159): two `createSignal`/`createMemo` shapes that
6391
+ * mis-compiled silently before this pass existed, because
6392
+ * `validateReactiveFactoryCalls` above unconditionally `continue`s past any
6393
+ * array-pattern destructure whose callee is `createSignal`/`createMemo` —
6394
+ * it exists to validate an UNRECOGNISED callee, and never checked whether a
6395
+ * RECOGNISED one was actually called with a shape it supports.
6396
+ *
6397
+ * - **BF115 — tuple arity.** `createSignal(...)` returns `[getter, setter]`:
6398
+ * a 1-element destructure keeps just the getter (`setter: null`,
6399
+ * supported), but `collectSignal`'s `elements.length > 2` guard silently
6400
+ * returns with NOTHING pushed to `ctx.signals` for anything wider — the
6401
+ * whole declaration vanishes from the compiled output, and a same-name
6402
+ * prop (`const [user, setUser, extra] = createSignal(props.user)` next to
6403
+ * a `user` prop) silently mis-seeds `user` as the raw prop accessor
6404
+ * instead of the signal. `createMemo(...)` returns a single getter, not a
6405
+ * tuple, so ANY array-pattern destructure of it is a mismatch (it isn't
6406
+ * even reachable through `collectMemo`, which requires an identifier
6407
+ * binding — so today it silently produces nothing at all, not even an
6408
+ * opaque local).
6409
+ * - **BF116 — extra arguments.** `createSignal(initialValue?)` takes 0 or 1
6410
+ * argument; `createMemo(computeFn)` takes exactly 1; an env-signal factory
6411
+ * (`createSearchParams()`) takes none. `collectSignal`/
6412
+ * `collectMemo` only ever read `arguments[0]`, so any argument beyond it
6413
+ * (`createSignal(props.user, { from: 'router' })`) is silently dropped
6414
+ * from the emitted client JS with no diagnostic.
6415
+ *
6416
+ * Recognises the callee via `resolvePrimitiveKind` — the same
6417
+ * TypeChecker-backed, alias/namespace-import-safe resolution
6418
+ * `isSignalDeclaration`/`isMemoDeclaration` use — rather than the bare
6419
+ * identifier-text match `validateReactiveFactoryCalls` uses for BF110, so
6420
+ * an aliased import (`import { createSignal as sig }`) is still caught.
6421
+ *
6422
+ * This walks the analyzer's own parse of the ORIGINAL source AST (Phase 1),
6423
+ * which runs strictly before Phase 2 client-JS emission — the compiler's
6424
+ * own profile-mode `__bfId` argument (`ir-to-client-js/stringify/
6425
+ * declaration-emit.ts`, `profiler.ts`) is inserted later, during emission,
6426
+ * so it can never appear in a call this pass inspects and needs no
6427
+ * special-casing here.
6428
+ */
6429
+ function validateReactiveFactoryArity(ctx: AnalyzerContext): void {
6430
+ if (!ctx.componentNode) return
6431
+ const body = ts.isFunctionDeclaration(ctx.componentNode)
6432
+ ? ctx.componentNode.body
6433
+ : (ts.isBlock(ctx.componentNode.body) ? ctx.componentNode.body : null)
6434
+ if (!body) return
6435
+
6436
+ checkStatementsForReactiveFactoryArity(body.statements, ctx)
6437
+
6438
+ // Conditional early-return branches get their own signal collection path
6439
+ // (#1414 cell #8 — `collectBranchSignals`, called from the "if statement
6440
+ // with JSX return" case in `visitComponentBody` above): a top-level `if`
6441
+ // whose then-branch returns JSX has its *direct* statements scanned for
6442
+ // `createSignal` declarations too, so a bad-arity call there mis-compiles
6443
+ // exactly like a top-level one would, and needs the same diagnostic — not
6444
+ // just the top-level scan above, which the branch's statements are never
6445
+ // members of.
6446
+ for (const stmt of body.statements) {
6447
+ if (!ts.isIfStatement(stmt)) continue
6448
+ if (!findJsxReturnInBlock(stmt.thenStatement)) continue
6449
+ if (!ts.isBlock(stmt.thenStatement)) continue
6450
+ checkStatementsForReactiveFactoryArity(stmt.thenStatement.statements, ctx)
6451
+ }
6452
+ }
6453
+
6454
+ /**
6455
+ * BF115/BF116 over one flat list of statements — shared by the component
6456
+ * body's top-level scan and the conditional-branch scan above, both of
6457
+ * which only ever look at direct variable-statement children (never
6458
+ * recursing further), matching exactly what `collectSignal`/`collectMemo`
6459
+ * are reachable from in each case.
6460
+ */
6461
+ function checkStatementsForReactiveFactoryArity(statements: readonly ts.Statement[], ctx: AnalyzerContext): void {
6462
+ for (const stmt of statements) {
6463
+ if (!ts.isVariableStatement(stmt)) continue
6464
+ for (const decl of stmt.declarationList.declarations) {
6465
+ if (!decl.initializer || !ts.isCallExpression(decl.initializer)) continue
6466
+ const callExpr = decl.initializer
6467
+ const kind = resolvePrimitiveKind(callExpr, ctx)
6468
+ if (kind !== 'signal' && kind !== 'memo') continue
6469
+
6470
+ const loc = getSourceLocation(stmt, ctx.sourceFile, ctx.filePath)
6471
+ const calleeText = callExpr.expression.getText(ctx.sourceFile)
6472
+
6473
+ // Async reactive factories (`createQuery(fn, options?)`, #3165) return
6474
+ // `[value, action]` and take a request function plus options.
6475
+ const factoryKind = kind === 'signal' ? resolveSignalFactoryKind(callExpr, ctx) : null
6476
+ if (factoryKind !== null) {
6477
+ checkAsyncFactoryArity(decl, callExpr, calleeText, loc, ctx)
6478
+ if (factoryKind === 'mutation') checkMutationInitialOption(callExpr, calleeText, ctx)
6479
+ continue
6480
+ }
6481
+
6482
+ // BF115: tuple-destructure arity. `createMemo` never returns a tuple
6483
+ // (maxArity 0 — any array-pattern destructure of it is a mismatch);
6484
+ // `createSignal` returns 1-2 elements.
6485
+ if (ts.isArrayBindingPattern(decl.name)) {
6486
+ const elementCount = decl.name.elements.length
6487
+ const maxArity = kind === 'signal' ? 2 : 0
6488
+ if (elementCount < 1 || elementCount > maxArity) {
6489
+ ctx.errors.push(createError(ErrorCodes.REACTIVE_FACTORY_ARITY_MISMATCH, loc, {
6490
+ severity: 'error',
6491
+ message: kind === 'signal'
6492
+ ? (elementCount === 0
6493
+ ? `'${calleeText}(...)' returns a 2-element tuple '[getter, setter]' — this ` +
6494
+ `destructure binds 0 elements, so neither the getter nor the setter is ` +
6495
+ `reachable. Use 'const [get, set] = ${calleeText}(...)' or ` +
6496
+ `'const [get] = ${calleeText}(...)'.`
6497
+ : `'${calleeText}(...)' returns a 2-element tuple '[getter, setter]' (a ` +
6498
+ `1-element destructure keeps just the getter) — this destructure has ` +
6499
+ `${elementCount} elements. The extra binding(s) are silently dropped from ` +
6500
+ `the compiled output today. Use 'const [get, set] = ${calleeText}(...)' or ` +
6501
+ `'const [get] = ${calleeText}(...)'.`)
6502
+ : `'${calleeText}(...)' returns a single getter function, not a tuple — this ` +
6503
+ `destructures ${elementCount} element${elementCount === 1 ? '' : 's'} from it. ` +
6504
+ `Use 'const value = ${calleeText}(...)' instead.`,
6505
+ }))
6506
+ // Already flagged for this shape; the argument-count check below
6507
+ // would be redundant noise on a declaration already rejected.
6508
+ continue
6509
+ }
6510
+ }
6511
+
6512
+ // BF116: extra call arguments. `createSignal`/`createMemo` accept at
6513
+ // most 1; an env-signal factory (`createSearchParams()`, which also
6514
+ // resolves to kind `'signal'`) takes none — its value comes from the
6515
+ // request env, so any argument is dropped just the same.
6516
+ const isEnvSignal = kind === 'signal' && resolveEnvSignalKey(callExpr, ctx) !== null
6517
+ const maxArgs = isEnvSignal ? 0 : 1
6518
+ if (callExpr.arguments.length > maxArgs) {
6519
+ ctx.errors.push(createError(ErrorCodes.REACTIVE_FACTORY_EXTRA_ARGUMENTS, loc, {
6520
+ severity: 'error',
6521
+ message: isEnvSignal
6522
+ ? `'${calleeText}()' takes no arguments (its value is read from the request ` +
6523
+ `environment), but this call passes ${callExpr.arguments.length}. The ` +
6524
+ `argument(s) are silently dropped from the compiled client JS today; remove them.`
6525
+ : `'${calleeText}(...)' accepts at most 1 argument (${kind === 'signal' ? 'the initial value' : 'the compute function'}), ` +
6526
+ `but this call passes ${callExpr.arguments.length}. The extra argument(s) are ` +
6527
+ `silently dropped from the compiled client JS today; remove them, or fold ` +
6528
+ `whatever they configure into the ${kind === 'signal' ? 'initial value expression' : 'compute function body'}.`,
6529
+ }))
6530
+ }
6531
+ }
6532
+ }
6533
+ }
6534
+
6535
+ /**
6536
+ * BF115 / BF116 for an async reactive factory (`createQuery(fn, options?)`,
6537
+ * #3165): it returns `[value, action]` (a 1-element destructure keeps just
6538
+ * the value; `[, action]` keeps just the action) and takes the request
6539
+ * function plus an optional options object. `collectFactorySignal` only
6540
+ * reads those two arguments, so a third would be dropped from the client JS.
6541
+ */
6542
+ function checkAsyncFactoryArity(
6543
+ decl: ts.VariableDeclaration,
6544
+ callExpr: ts.CallExpression,
6545
+ calleeText: string,
6546
+ loc: SourceLocation,
6547
+ ctx: AnalyzerContext,
6548
+ ): void {
6549
+ if (ts.isArrayBindingPattern(decl.name)) {
6550
+ const elementCount = decl.name.elements.length
6551
+ if (elementCount < 1 || elementCount > 2) {
6552
+ ctx.errors.push(createError(ErrorCodes.REACTIVE_FACTORY_ARITY_MISMATCH, loc, {
6553
+ severity: 'error',
6554
+ message:
6555
+ `'${calleeText}(...)' returns a 2-element tuple '[value, action]' — this destructure has ` +
6556
+ `${elementCount} elements. Use 'const [value, action] = ${calleeText}(...)', ` +
6557
+ `'const [value] = ${calleeText}(...)' or 'const [, action] = ${calleeText}(...)'.`,
6558
+ }))
6559
+ return
6560
+ }
6561
+ }
6562
+ if (callExpr.arguments.length > 2) {
6563
+ ctx.errors.push(createError(ErrorCodes.REACTIVE_FACTORY_EXTRA_ARGUMENTS, loc, {
6564
+ severity: 'error',
6565
+ message:
6566
+ `'${calleeText}(...)' accepts at most 2 arguments (the request function and the options), ` +
6567
+ `but this call passes ${callExpr.arguments.length}. The extra argument(s) are dropped from the ` +
6568
+ `compiled client JS; remove them.`,
6569
+ }))
6570
+ }
6571
+ }
6572
+
6573
+ /**
6574
+ * BF118 (#3210): an `initial` key in `createMutation`'s options. A mutation's
6575
+ * value is `undefined` until its action is called (spec/async.md §7.4), and
6576
+ * the runtime ignores the key, so an author who writes it expects a seed
6577
+ * that never happens. Only an object-literal `options` is read, the same
6578
+ * structural read `createQuery`'s `initial` goes through; any other shape
6579
+ * carries no key the compiler can see.
6580
+ */
6581
+ function checkMutationInitialOption(callExpr: ts.CallExpression, calleeText: string, ctx: AnalyzerContext): void {
6582
+ const initialNode = factoryInitialNode(callExpr.arguments[1])
6583
+ if (initialNode.kind !== 'expression') return
6584
+ ctx.errors.push(createError(ErrorCodes.MUTATION_INITIAL_OPTION, getSourceLocation(initialNode.node, ctx.sourceFile, ctx.filePath), {
6585
+ severity: 'error',
6586
+ message:
6587
+ `'${calleeText}(...)' takes no 'initial' option: a mutation's value is undefined until its action is ` +
6588
+ `called, so this value would never be used. Use 'createQuery' for a value that needs an initial state.`,
6589
+ }))
6590
+ }
6591
+
6067
6592
  /**
6068
6593
  * BF013 (#2771): a reactive primitive called through a namespace import
6069
6594
  * (`import * as bf from '@barefootjs/client'`, `bf.createSignal(...)`)