@barefootjs/jsx 0.40.1 → 0.41.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 (211) hide show
  1. package/dist/adapters/boolean-result.d.ts +32 -10
  2. package/dist/adapters/boolean-result.d.ts.map +1 -1
  3. package/dist/adapters/brace-delimiter-text.d.ts +18 -0
  4. package/dist/adapters/brace-delimiter-text.d.ts.map +1 -0
  5. package/dist/adapters/callback-method.d.ts +45 -5
  6. package/dist/adapters/callback-method.d.ts.map +1 -1
  7. package/dist/adapters/component-props.d.ts +3 -4
  8. package/dist/adapters/component-props.d.ts.map +1 -1
  9. package/dist/adapters/computed-const.d.ts +11 -1
  10. package/dist/adapters/computed-const.d.ts.map +1 -1
  11. package/dist/adapters/dsl-template-adapter.d.ts +24 -12
  12. package/dist/adapters/dsl-template-adapter.d.ts.map +1 -1
  13. package/dist/adapters/loop-bound-names.d.ts +9 -1
  14. package/dist/adapters/loop-bound-names.d.ts.map +1 -1
  15. package/dist/adapters/loop-row-type.d.ts +59 -0
  16. package/dist/adapters/loop-row-type.d.ts.map +1 -0
  17. package/dist/adapters/nil-reading.d.ts +63 -0
  18. package/dist/adapters/nil-reading.d.ts.map +1 -0
  19. package/dist/adapters/non-primitive-equality.d.ts +33 -0
  20. package/dist/adapters/non-primitive-equality.d.ts.map +1 -0
  21. package/dist/adapters/number-value.d.ts +5 -3
  22. package/dist/adapters/number-value.d.ts.map +1 -1
  23. package/dist/adapters/operand-typing.d.ts +126 -0
  24. package/dist/adapters/operand-typing.d.ts.map +1 -0
  25. package/dist/adapters/parsed-expr-emitter.d.ts +80 -12
  26. package/dist/adapters/parsed-expr-emitter.d.ts.map +1 -1
  27. package/dist/adapters/primitive-plan.d.ts +320 -0
  28. package/dist/adapters/primitive-plan.d.ts.map +1 -0
  29. package/dist/adapters/prop-classes.d.ts +5 -0
  30. package/dist/adapters/prop-classes.d.ts.map +1 -1
  31. package/dist/analyzer-context.d.ts +4 -0
  32. package/dist/analyzer-context.d.ts.map +1 -1
  33. package/dist/analyzer.d.ts.map +1 -1
  34. package/dist/augment-inherited-props.d.ts +63 -8
  35. package/dist/augment-inherited-props.d.ts.map +1 -1
  36. package/dist/compiler.d.ts.map +1 -1
  37. package/dist/event-handler-name.d.ts +12 -0
  38. package/dist/event-handler-name.d.ts.map +1 -1
  39. package/dist/expression-parser.d.ts +8 -0
  40. package/dist/expression-parser.d.ts.map +1 -1
  41. package/dist/index.d.ts +20 -11
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +4903 -2311
  44. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/child-props-object.d.ts +106 -0
  46. package/dist/ir-to-client-js/child-props-object.d.ts.map +1 -0
  47. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/control-flow/plan/build-inner-loop.d.ts.map +1 -1
  49. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  51. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts +4 -2
  52. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts.map +1 -1
  53. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  54. package/dist/ir-to-client-js/imports.d.ts +2 -2
  55. package/dist/ir-to-client-js/imports.d.ts.map +1 -1
  56. package/dist/ir-to-client-js/index.d.ts +2 -6
  57. package/dist/ir-to-client-js/index.d.ts.map +1 -1
  58. package/dist/ir-to-client-js/phases/props-extraction.d.ts +3 -3
  59. package/dist/ir-to-client-js/plan/build-declaration-emit.d.ts.map +1 -1
  60. package/dist/ir-to-client-js/plan/build-static-array-child-init.d.ts.map +1 -1
  61. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts +30 -18
  62. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts.map +1 -1
  63. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  64. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts +3 -1
  65. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts.map +1 -1
  66. package/dist/ir-to-client-js/stringify/static-array-child-init.d.ts +3 -2
  67. package/dist/ir-to-client-js/stringify/static-array-child-init.d.ts.map +1 -1
  68. package/dist/jsx-to-ir.d.ts +1 -0
  69. package/dist/jsx-to-ir.d.ts.map +1 -1
  70. package/dist/nullable-signal-attr.d.ts +51 -34
  71. package/dist/nullable-signal-attr.d.ts.map +1 -1
  72. package/dist/prop-rewrite.d.ts +7 -0
  73. package/dist/prop-rewrite.d.ts.map +1 -1
  74. package/dist/props-binding.d.ts +58 -13
  75. package/dist/props-binding.d.ts.map +1 -1
  76. package/dist/props-object-whole-read.d.ts +15 -0
  77. package/dist/props-object-whole-read.d.ts.map +1 -0
  78. package/dist/rich-type-refusal.d.ts.map +1 -1
  79. package/dist/scope/binding-scope.d.ts +85 -10
  80. package/dist/scope/binding-scope.d.ts.map +1 -1
  81. package/dist/scope/lexical-scope-walk.d.ts +3 -2
  82. package/dist/scope/lexical-scope-walk.d.ts.map +1 -1
  83. package/dist/scope/root-prop-alias.d.ts +10 -7
  84. package/dist/scope/root-prop-alias.d.ts.map +1 -1
  85. package/dist/ssr-defaults.d.ts +39 -3
  86. package/dist/ssr-defaults.d.ts.map +1 -1
  87. package/dist/strip-types.d.ts +13 -0
  88. package/dist/strip-types.d.ts.map +1 -1
  89. package/dist/template-position-walk.d.ts +21 -3
  90. package/dist/template-position-walk.d.ts.map +1 -1
  91. package/dist/types.d.ts +90 -0
  92. package/dist/types.d.ts.map +1 -1
  93. package/package.json +2 -2
  94. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +9 -9
  95. package/src/__tests__/binding-scope.test.ts +89 -1
  96. package/src/__tests__/body-destructure-props-object-alias.test.ts +123 -0
  97. package/src/__tests__/body-destructured-prop-default-arrow.test.ts +2 -2
  98. package/src/__tests__/body-destructured-props-live.test.ts +5 -5
  99. package/src/__tests__/boolean-result.test.ts +22 -5
  100. package/src/__tests__/brace-delimiter-text.test.ts +26 -0
  101. package/src/__tests__/callback-method.test.ts +62 -2
  102. package/src/__tests__/child-components-in-map.test.ts +1 -1
  103. package/src/__tests__/client-js-generation.test.ts +3 -3
  104. package/src/__tests__/computed-const.test.ts +103 -0
  105. package/src/__tests__/destructure-default-reads-earlier-param.test.ts +7 -7
  106. package/src/__tests__/destructured-props-live.test.ts +1 -1
  107. package/src/__tests__/emit-to-string-call.test.ts +2 -1
  108. package/src/__tests__/hydration-payload-analysis.test.ts +166 -0
  109. package/src/__tests__/issue-2724-prop-alias-loop-not-static.test.ts +7 -7
  110. package/src/__tests__/issue-2754-rest-spread-needs-slot.test.ts +5 -2
  111. package/src/__tests__/issue-2798-static-nested-loop-bindings.test.ts +1 -1
  112. package/src/__tests__/issue-2835-props-type-member-name-collision.test.ts +4 -4
  113. package/src/__tests__/issue-3044-nested-prop-object-array-not-static.test.ts +1 -1
  114. package/src/__tests__/issue-3688-props-spread-child-csr.test.ts +2 -1
  115. package/src/__tests__/issue-3713-props-spread-loop-row.test.ts +65 -0
  116. package/src/__tests__/issue-3861-object-spread-child.test.ts +102 -0
  117. package/src/__tests__/lookup-literal-const.test.ts +9 -3
  118. package/src/__tests__/loop-index-reactivity.test.ts +2 -2
  119. package/src/__tests__/loop-param-accessor-key-member-safety.test.ts +1 -1
  120. package/src/__tests__/loop-plan.test.ts +1 -1
  121. package/src/__tests__/loop-row-const-initializer-shadow.test.ts +146 -0
  122. package/src/__tests__/loop-row-type.test.ts +64 -0
  123. package/src/__tests__/lowering-value-position.test.ts +4 -0
  124. package/src/__tests__/memo-body-expr.test.ts +2 -2
  125. package/src/__tests__/module-const-destructure-default.test.ts +156 -0
  126. package/src/__tests__/nested-loop-index-param.test.ts +1 -1
  127. package/src/__tests__/nested-loop-reactive-attrs.test.ts +2 -2
  128. package/src/__tests__/nested-row-shadowing.test.ts +2 -2
  129. package/src/__tests__/nil-reading.test.ts +78 -0
  130. package/src/__tests__/nullable-signal-attr.test.ts +109 -48
  131. package/src/__tests__/primitive-plan.test.ts +494 -0
  132. package/src/__tests__/profile-loop-binding-ids.test.ts +2 -2
  133. package/src/__tests__/profile-nested-binding-ids.test.ts +2 -2
  134. package/src/__tests__/prop-default-undefined-only.test.ts +115 -0
  135. package/src/__tests__/prop-references.test.ts +2 -2
  136. package/src/__tests__/props-destructuring.test.ts +17 -0
  137. package/src/__tests__/props-object-whole-read.test.ts +40 -0
  138. package/src/__tests__/prune-unused-prop-extractions.test.ts +3 -3
  139. package/src/__tests__/reactive-attrs-in-map.test.ts +1 -1
  140. package/src/__tests__/reactive-factory-inlining.test.ts +4 -1
  141. package/src/__tests__/renamed-body-destructure-template.test.ts +7 -7
  142. package/src/__tests__/rest-binding-gaps.test.ts +192 -0
  143. package/src/__tests__/rewrite-destructured-props.test.ts +1 -1
  144. package/src/__tests__/root-prop-alias.test.ts +53 -8
  145. package/src/__tests__/ssr-defaults.test.ts +113 -25
  146. package/src/__tests__/static-loop-csr-materialize.test.ts +2 -2
  147. package/src/__tests__/static-record-literal-array.test.ts +171 -0
  148. package/src/__tests__/string-concat-identifier.test.ts +40 -1
  149. package/src/__tests__/written-binding-substitution.test.ts +8 -8
  150. package/src/adapters/boolean-result.ts +72 -66
  151. package/src/adapters/brace-delimiter-text.ts +25 -0
  152. package/src/adapters/callback-method.ts +159 -27
  153. package/src/adapters/component-props.ts +3 -4
  154. package/src/adapters/computed-const.ts +238 -4
  155. package/src/adapters/dsl-template-adapter.ts +62 -26
  156. package/src/adapters/loop-bound-names.ts +9 -1
  157. package/src/adapters/loop-plan.ts +1 -1
  158. package/src/adapters/loop-row-type.ts +149 -0
  159. package/src/adapters/nil-reading.ts +295 -0
  160. package/src/adapters/non-primitive-equality.ts +92 -0
  161. package/src/adapters/number-value.ts +17 -4
  162. package/src/adapters/operand-typing.ts +522 -0
  163. package/src/adapters/parsed-expr-emitter.ts +183 -19
  164. package/src/adapters/primitive-plan.ts +765 -0
  165. package/src/adapters/prop-classes.ts +16 -3
  166. package/src/analyzer-context.ts +6 -0
  167. package/src/analyzer.ts +532 -26
  168. package/src/augment-inherited-props.ts +108 -10
  169. package/src/compiler.ts +17 -0
  170. package/src/event-handler-name.ts +15 -0
  171. package/src/expression-parser.ts +70 -1
  172. package/src/index.ts +35 -16
  173. package/src/ir-to-client-js/build-references.ts +69 -0
  174. package/src/ir-to-client-js/child-props-object.ts +240 -0
  175. package/src/ir-to-client-js/collect-elements.ts +31 -63
  176. package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts +8 -1
  177. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +31 -28
  178. package/src/ir-to-client-js/control-flow/shared.ts +20 -22
  179. package/src/ir-to-client-js/control-flow/stringify/claim-plan.ts +5 -3
  180. package/src/ir-to-client-js/control-flow/stringify/inner-loop.ts +2 -2
  181. package/src/ir-to-client-js/control-flow/stringify/lazy-row.ts +1 -1
  182. package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts +2 -2
  183. package/src/ir-to-client-js/control-flow/stringify/loop.ts +1 -1
  184. package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts +3 -3
  185. package/src/ir-to-client-js/html-template.ts +43 -17
  186. package/src/ir-to-client-js/imports.ts +2 -2
  187. package/src/ir-to-client-js/index.ts +53 -11
  188. package/src/ir-to-client-js/phases/props-extraction.ts +11 -7
  189. package/src/ir-to-client-js/plan/build-declaration-emit.ts +40 -7
  190. package/src/ir-to-client-js/plan/build-static-array-child-init.ts +31 -14
  191. package/src/ir-to-client-js/plan/static-array-child-init.ts +27 -18
  192. package/src/ir-to-client-js/prop-handling.ts +22 -3
  193. package/src/ir-to-client-js/prune-unused-prop-extractions.ts +58 -5
  194. package/src/ir-to-client-js/rewrite-destructured-props.ts +31 -1
  195. package/src/ir-to-client-js/stringify/static-array-child-init.ts +26 -10
  196. package/src/jsx-to-ir.ts +459 -37
  197. package/src/nullable-signal-attr.ts +200 -110
  198. package/src/prop-rewrite.ts +30 -6
  199. package/src/props-binding.ts +84 -19
  200. package/src/props-object-whole-read.ts +87 -0
  201. package/src/rich-type-refusal.ts +2 -1
  202. package/src/scope/binding-scope.ts +182 -18
  203. package/src/scope/lexical-scope-walk.ts +4 -3
  204. package/src/scope/root-prop-alias.ts +15 -8
  205. package/src/ssr-defaults.ts +100 -11
  206. package/src/strip-types.ts +31 -3
  207. package/src/template-position-walk.ts +57 -28
  208. package/src/types.ts +87 -0
  209. package/dist/adapters/ambiguous-nil-arithmetic.d.ts +0 -41
  210. package/dist/adapters/ambiguous-nil-arithmetic.d.ts.map +0 -1
  211. package/src/adapters/ambiguous-nil-arithmetic.ts +0 -94
@@ -0,0 +1,522 @@
1
+ /**
2
+ * Operand typing for the JS primitive plan (`spec/js-primitive-semantics.md`,
3
+ * "Decision point"). One `collectOperandTyping` per component reads the
4
+ * Phase-1 metadata (props with their optionality and declared types, signals,
5
+ * memos, local constants, named types) into the facts a name read proves;
6
+ * `typing.at(scope)` sees it through a `BindingScope`, so a loop or callback
7
+ * binding shadows an outer name and a row read takes its type from
8
+ * `ScopeBinding.row` (as `BindingScope.isStringValueName` does for strings).
9
+ *
10
+ * This module only answers "what does a read of this name prove". The
11
+ * expression-level classifier is `operandFacts` (`primitive-plan.ts`).
12
+ */
13
+
14
+ import type { IRMetadata, TypeInfo } from '../types.ts'
15
+ import type { ParsedExpr } from '../expression-parser.ts'
16
+ import {
17
+ BindingScope,
18
+ PROPS_OBJECT_IDENTIFIER,
19
+ loopValueTypeAt,
20
+ type LoopValueType,
21
+ type NamedTypeFields,
22
+ type ScopeBinding,
23
+ } from '../scope/binding-scope.ts'
24
+
25
+ /** A JS type an operand can have at its read; `unknown` when not proven. */
26
+ export type OperandType = 'number' | 'string' | 'boolean' | 'nil' | 'object' | 'unknown'
27
+
28
+ /** Which JS value a host nil stands for at a read. */
29
+ export type NilReading = 'null' | 'undefined' | 'either'
30
+
31
+ /** What Phase-1 types prove about an operand at its read. */
32
+ export interface OperandFacts {
33
+ /** The JS types the value can have; `unknown` when not proven. */
34
+ readonly types: ReadonlySet<OperandType>
35
+ /** Which JS value a nil stands for, when `types` has `nil`. */
36
+ readonly nil?: NilReading
37
+ /** A non-negative integer (a loop index binding). */
38
+ readonly index?: boolean
39
+ /**
40
+ * The value is an array. Not in the design note's sketch: the `get` plan's
41
+ * `array-index` proof needs the receiver proven an array, and `object`
42
+ * alone does not tell an array from a record.
43
+ */
44
+ readonly array?: boolean
45
+ /**
46
+ * What an element proves when the value is or may be an array and the
47
+ * declared element type or the array-literal seed says (#3824 step 8:
48
+ * `===` refuses an element read that may be an object). A union keeps it
49
+ * from any member that has it (`rows?: Row[]` is `Row[]` or nil), so it is
50
+ * possible-object evidence only and never proves the value an array:
51
+ * `array` does that. Read only by `mayHoldObject`; no plan reads it.
52
+ */
53
+ readonly element?: OperandFacts
54
+ /**
55
+ * When `types` has `object` only because of named type references (a
56
+ * declared `Row` or `Tone`, which Phase 1 types as `interface` whatever
57
+ * the name resolves to): those names. Absent when a structural object
58
+ * type or literal contributed `object`. Read only by `mayHoldObject`
59
+ * (#3824 step 8), which resolves the names against the component's type
60
+ * definitions: `type Tone = 'warm' | 'cool'` is not an object.
61
+ */
62
+ readonly namedObjects?: readonly string[]
63
+ }
64
+
65
+ /** Facts proving nothing. */
66
+ export const UNKNOWN_FACTS: OperandFacts = { types: new Set<OperandType>(['unknown']) }
67
+
68
+ /** Facts of a value of exactly one JS type (never nil). */
69
+ export function factsOf(type: Exclude<OperandType, 'nil' | 'unknown'>): OperandFacts {
70
+ return { types: new Set<OperandType>([type]) }
71
+ }
72
+
73
+ /** Facts of a nil read as `reading`. */
74
+ export function nilFacts(reading: Exclude<NilReading, 'either'>): OperandFacts {
75
+ return { types: new Set<OperandType>(['nil']), nil: reading }
76
+ }
77
+
78
+ function mergeNil(a: NilReading | undefined, b: NilReading | undefined): NilReading | undefined {
79
+ if (a === undefined) return b
80
+ if (b === undefined || a === b) return a
81
+ return 'either'
82
+ }
83
+
84
+ /**
85
+ * The facts of a value that is one of `a` or `b`. An unknown member makes the
86
+ * whole value unknown; `index` and `array` hold only when both hold, while
87
+ * `element` is kept from either member ({@link mergeElement}).
88
+ */
89
+ export function unionFacts(a: OperandFacts, b: OperandFacts): OperandFacts {
90
+ if (a.types.has('unknown') || b.types.has('unknown')) return UNKNOWN_FACTS
91
+ const types = new Set<OperandType>([...a.types, ...b.types])
92
+ const nil = mergeNil(a.nil, b.nil)
93
+ const namedObjects = mergeNamedObjects(a, b)
94
+ const element = mergeElement(a.element, b.element)
95
+ return {
96
+ types,
97
+ ...(nil !== undefined ? { nil } : {}),
98
+ ...(a.index && b.index ? { index: true } : {}),
99
+ ...(a.array && b.array ? { array: true } : {}),
100
+ ...(element ? { element } : {}),
101
+ ...(namedObjects ? { namedObjects } : {}),
102
+ }
103
+ }
104
+
105
+ /**
106
+ * The `element` of a union, as possible-object evidence: the one member's
107
+ * when only one has it (a nil or non-array member has no elements), else
108
+ * their union, or, when that proves nothing, the member whose elements may be
109
+ * objects (an unknown element type must not erase a known `Row`).
110
+ */
111
+ function mergeElement(a: OperandFacts | undefined, b: OperandFacts | undefined): OperandFacts | undefined {
112
+ if (!a || !b) return a ?? b
113
+ const both = unionFacts(a, b)
114
+ if (!both.types.has('unknown')) return both
115
+ return a.types.has('object') ? a : b
116
+ }
117
+
118
+ /** The `namedObjects` of a union: kept only while every `object` member came from a named reference. */
119
+ function mergeNamedObjects(a: OperandFacts, b: OperandFacts): readonly string[] | undefined {
120
+ const ao = a.types.has('object')
121
+ const bo = b.types.has('object')
122
+ if (ao && bo) return a.namedObjects && b.namedObjects ? [...a.namedObjects, ...b.namedObjects] : undefined
123
+ return ao ? a.namedObjects : bo ? b.namedObjects : undefined
124
+ }
125
+
126
+ /** `facts` with the nil member removed (the value after a `??`). */
127
+ export function withoutNil(facts: OperandFacts): OperandFacts {
128
+ if (!facts.types.has('nil')) return facts
129
+ const types = new Set(facts.types)
130
+ types.delete('nil')
131
+ if (types.size === 0) return UNKNOWN_FACTS
132
+ return {
133
+ types,
134
+ ...(facts.index ? { index: true } : {}),
135
+ ...(facts.array ? { array: true } : {}),
136
+ ...(facts.element ? { element: facts.element } : {}),
137
+ ...(facts.namedObjects ? { namedObjects: facts.namedObjects } : {}),
138
+ }
139
+ }
140
+
141
+ /** `facts` that may also be nil read as `reading`. */
142
+ export function withNil(facts: OperandFacts, reading: Exclude<NilReading, 'either'>): OperandFacts {
143
+ return unionFacts(facts, nilFacts(reading))
144
+ }
145
+
146
+ /** Whether `facts` prove exactly the one type `type`, never nil. */
147
+ export function isExactly(facts: OperandFacts, type: OperandType): boolean {
148
+ return facts.types.size === 1 && facts.types.has(type)
149
+ }
150
+
151
+ /** The one primitive type `facts` prove (never nil), or null. */
152
+ export function provenPrimitive(facts: OperandFacts): 'number' | 'string' | 'boolean' | null {
153
+ if (facts.types.size !== 1) return null
154
+ const [only] = facts.types
155
+ return only === 'number' || only === 'string' || only === 'boolean' ? only : null
156
+ }
157
+
158
+ /** Whether `facts` prove the value is never nil. */
159
+ export function isNeverNil(facts: OperandFacts): boolean {
160
+ return !facts.types.has('nil') && !facts.types.has('unknown')
161
+ }
162
+
163
+ /** The facts of a declared type (a `TypeInfo`, or the structural `LoopValueType` a row carries). */
164
+ export function factsOfType(type: LoopValueType | null | undefined): OperandFacts {
165
+ if (!type) return UNKNOWN_FACTS
166
+ if (type.kind === 'primitive') return factsOfPrimitive(type.primitive)
167
+ if (type.kind === 'union' && type.unionTypes && type.unionTypes.length > 0) {
168
+ return type.unionTypes.map(factsOfType).reduce(unionFacts)
169
+ }
170
+ if (type.kind === 'array') {
171
+ const element = type.elementType ? factsOfType(type.elementType) : undefined
172
+ return { types: new Set<OperandType>(['object']), array: true, ...(element ? { element } : {}) }
173
+ }
174
+ if (type.kind === 'interface') return { types: new Set<OperandType>(['object']), namedObjects: [type.raw ?? ''] }
175
+ if (type.kind === 'object') return factsOf('object')
176
+ return UNKNOWN_FACTS
177
+ }
178
+
179
+ /**
180
+ * What an element of an array-literal seed proves (`createSignal([{ id: 1 }])`
181
+ * is typed `unknown[]`): the union of its elements' literal facts, an object
182
+ * or array literal element proving `object`. Unknown when an element proves
183
+ * nothing or the literal is empty.
184
+ */
185
+ function arrayLiteralElementFacts(seed: Extract<ParsedExpr, { kind: 'array-literal' }>): OperandFacts {
186
+ if (seed.elements.length === 0) return UNKNOWN_FACTS
187
+ return seed.elements
188
+ .map((e): OperandFacts => {
189
+ if (e.kind === 'object-literal') return factsOf('object')
190
+ if (e.kind === 'array-literal') return { types: new Set<OperandType>(['object']), array: true }
191
+ return factsOfLiteral(e) ?? UNKNOWN_FACTS
192
+ })
193
+ .reduce(unionFacts)
194
+ }
195
+
196
+ function factsOfPrimitive(primitive: string | undefined): OperandFacts {
197
+ if (primitive === 'string' || primitive === 'number' || primitive === 'boolean') return factsOf(primitive)
198
+ if (primitive === 'null') return nilFacts('null')
199
+ if (primitive === 'undefined') return nilFacts('undefined')
200
+ return UNKNOWN_FACTS
201
+ }
202
+
203
+ const COMPARISON_OPS: ReadonlySet<string> = new Set(['<', '>', '<=', '>=', '==', '===', '!=', '!=='])
204
+
205
+ /**
206
+ * The facts of a literal initializer (`createSignal(0)`, `const x = 'a'`),
207
+ * or of one that always yields a boolean (`createSignal(n > 1)`,
208
+ * `const off = !on`, #3824 step 5); null when it is neither.
209
+ */
210
+ function factsOfLiteral(parsed: ParsedExpr | undefined): OperandFacts | null {
211
+ if (!parsed) return null
212
+ if (parsed.kind === 'identifier' && parsed.name === 'undefined') return nilFacts('undefined')
213
+ if (parsed.kind === 'binary' && COMPARISON_OPS.has(parsed.op)) return factsOf('boolean')
214
+ if (parsed.kind === 'unary' && parsed.op === '!') return factsOf('boolean')
215
+ if (parsed.kind !== 'literal') return null
216
+ return parsed.literalType === 'null' ? nilFacts('null') : factsOf(parsed.literalType)
217
+ }
218
+
219
+ /**
220
+ * A local constant's facts: a declared type that proves something, else a
221
+ * body destructure's ({@link bodyDestructureFacts}), else its initializer's
222
+ * (`const text = props.label ?? 'x'` is never nil: `??` replaces `null` too).
223
+ */
224
+ function constantFacts(
225
+ constant: TypingMetadata['localConstants'][number],
226
+ params: TypingMetadata['propsParams'],
227
+ typed: TypedNames,
228
+ ): OperandFacts {
229
+ const declared = factsOfType(constant.type)
230
+ if (!declared.types.has('unknown')) return declared
231
+ if (constant.propsDestructure) return bodyDestructureFacts(constant, constant.propsDestructure.sourceKey, params, typed)
232
+ return initializerFacts(constant.parsed, typed) ?? UNKNOWN_FACTS
233
+ }
234
+
235
+ /** A declared type that proves something, else the literal seed's facts. */
236
+ function declaredOrSeeded(type: TypeInfo | null | undefined, seed: ParsedExpr | undefined): OperandFacts {
237
+ const declared = factsOfType(type)
238
+ if (declared.array && !declared.element && seed?.kind === 'array-literal') {
239
+ return { ...declared, element: arrayLiteralElementFacts(seed) }
240
+ }
241
+ if (!declared.types.has('unknown')) return declared
242
+ return factsOfLiteral(seed) ?? UNKNOWN_FACTS
243
+ }
244
+
245
+ /** The component-level operand typing, built once per component. */
246
+ export interface OperandTyping {
247
+ /** This typing seen through `scope`. */
248
+ at(scope: BindingScope): ScopedOperandTyping
249
+ }
250
+
251
+ /**
252
+ * {@link OperandTyping} at one emission site. Every answer respects the
253
+ * nearest binding: a loop row, a callback param or a preamble local shadows
254
+ * an outer name.
255
+ */
256
+ export interface ScopedOperandTyping {
257
+ readonly scope: BindingScope
258
+ /** A bare-name read: an identifier, or a zero-argument getter call. */
259
+ name(name: string): OperandFacts
260
+ /** The literal `props.<key>` read. */
261
+ prop(key: string): OperandFacts
262
+ /** The member chain `root.<path…>` (`row.id`); `name(root)` for an empty path. */
263
+ path(root: string, path: readonly string[]): OperandFacts
264
+ /**
265
+ * This typing inside a callback whose `params` bind (`BindingScope.enterCallback`):
266
+ * each param shadows an outer name and proves nothing itself.
267
+ */
268
+ enterCallback(params: readonly string[]): ScopedOperandTyping
269
+ }
270
+
271
+ export interface OperandTypingOptions {
272
+ /** The fields of a named type, for a row read through a named element type. */
273
+ readonly namedFields?: NamedTypeFields
274
+ }
275
+
276
+ type TypingMetadata = Pick<
277
+ IRMetadata,
278
+ 'signals' | 'memos' | 'propsParams' | 'localConstants' | 'propsObjectName' | 'typeDefinitions'
279
+ >
280
+
281
+ /** The names and `props.<key>` reads typed so far, which an initializer can read. */
282
+ interface TypedNames {
283
+ readonly names: ReadonlyMap<string, OperandFacts>
284
+ readonly props: ReadonlyMap<string, OperandFacts>
285
+ /** The identifier naming the component's props object, when it has one. */
286
+ readonly propsObject: string | null
287
+ }
288
+
289
+ /**
290
+ * What an initializer or default expression proves, read at component
291
+ * level: a literal, a template literal, an array or object literal, a read
292
+ * of a name or prop typed so far, `l ?? r` (the left side without its nil,
293
+ * or the right side) and `c ? a : b`. Null when the expression proves
294
+ * nothing, so a default whose value is not provable never proves non-nil.
295
+ */
296
+ function initializerFacts(expr: ParsedExpr | undefined, typed: TypedNames): OperandFacts | null {
297
+ if (!expr) return null
298
+ const literal = factsOfLiteral(expr)
299
+ if (literal) return literal
300
+ switch (expr.kind) {
301
+ case 'template-literal':
302
+ return factsOf('string')
303
+ case 'array-literal':
304
+ return { types: new Set<OperandType>(['object']), array: true }
305
+ case 'object-literal':
306
+ return factsOf('object')
307
+ case 'identifier':
308
+ return typed.names.get(expr.name) ?? null
309
+ case 'member':
310
+ return propsMemberFacts(expr, typed)
311
+ case 'logical':
312
+ return expr.op === '??' ? nullishFacts(expr.left, expr.right, typed) : null
313
+ case 'conditional':
314
+ return bothFacts(expr.consequent, expr.alternate, typed)
315
+ default:
316
+ return null
317
+ }
318
+ }
319
+
320
+ /** `<propsObject>.<key>`: the prop's facts; null for any other member. */
321
+ function propsMemberFacts(expr: Extract<ParsedExpr, { kind: 'member' }>, typed: TypedNames): OperandFacts | null {
322
+ const isPropsRead = !expr.computed && expr.object.kind === 'identifier' && expr.object.name === typed.propsObject
323
+ return isPropsRead ? (typed.props.get(expr.property) ?? null) : null
324
+ }
325
+
326
+ function nullishFacts(left: ParsedExpr, right: ParsedExpr, typed: TypedNames): OperandFacts | null {
327
+ const l = initializerFacts(left, typed)
328
+ const r = initializerFacts(right, typed)
329
+ if (!r) return null
330
+ // `l ?? r` is `r` whenever `l` is nil, and `l` (never nil) otherwise.
331
+ return l ? unionFacts(withoutNil(l), r) : null
332
+ }
333
+
334
+ function bothFacts(a: ParsedExpr, b: ParsedExpr, typed: TypedNames): OperandFacts | null {
335
+ const fa = initializerFacts(a, typed)
336
+ const fb = initializerFacts(b, typed)
337
+ return fa && fb ? unionFacts(fa, fb) : null
338
+ }
339
+
340
+ /** A prop's declared facts: its declared type, and `undefined` when it may be omitted. */
341
+ function declaredPropFacts(param: TypingMetadata['propsParams'][number]): OperandFacts {
342
+ const declared = factsOfType(param.declaredType ?? param.type)
343
+ return param.optional ? withNil(declared, 'undefined') : declared
344
+ }
345
+
346
+ /**
347
+ * `facts` once a destructuring default has replaced `undefined`: JS applies
348
+ * the default to `undefined` only, so a `null` survives it. A nil read as
349
+ * `either` keeps its `null`; null when nothing but `undefined` was possible.
350
+ */
351
+ function withoutUndefined(facts: OperandFacts): OperandFacts | null {
352
+ if (facts.nil === undefined || facts.nil === 'null') return facts
353
+ if (facts.nil === 'either') return { ...facts, nil: 'null' }
354
+ return facts.types.size === 1 ? null : withoutNil(facts)
355
+ }
356
+
357
+ /**
358
+ * The facts of a destructured binding (`{ n = 1 }`, `const { label: text = 'x' } = props`)
359
+ * of a value with `declared` facts: with a default, the value without its
360
+ * `undefined`, or the default's facts (`{ on = undefined }` may still be
361
+ * `undefined`, a `label?: string | null` may still be `null`). A default that
362
+ * proves nothing makes the binding unknown.
363
+ */
364
+ function destructuredFacts(declared: OperandFacts, fallbackExpr: ParsedExpr | undefined, hasDefault: boolean, typed: TypedNames): OperandFacts {
365
+ if (!hasDefault) return declared
366
+ const fallback = initializerFacts(fallbackExpr, typed)
367
+ if (!fallback) return UNKNOWN_FACTS
368
+ const kept = withoutUndefined(declared)
369
+ return kept ? unionFacts(kept, fallback) : fallback
370
+ }
371
+
372
+ /** A destructured prop parameter's facts ({@link destructuredFacts}). */
373
+ function boundPropFacts(param: TypingMetadata['propsParams'][number], typed: TypedNames): OperandFacts {
374
+ return destructuredFacts(declaredPropFacts(param), param.parsed, param.defaultValue !== undefined, typed)
375
+ }
376
+
377
+ /**
378
+ * A body destructure of the props object (`ConstantInfo.propsDestructure`):
379
+ * the prop's declared facts under the binding's own default
380
+ * ({@link destructuredFacts}), which the `propsParams` entry of the same
381
+ * name and key carries. Its initializer text (`props.label ?? 'x'`) is not
382
+ * read as a `??`: a destructuring default does not replace `null`.
383
+ */
384
+ function bodyDestructureFacts(
385
+ constant: TypingMetadata['localConstants'][number],
386
+ sourceKey: string,
387
+ params: TypingMetadata['propsParams'],
388
+ typed: TypedNames,
389
+ ): OperandFacts {
390
+ const declared = typed.props.get(sourceKey) ?? UNKNOWN_FACTS
391
+ const param = params.find(p => p.name === constant.name && (p.sourceName ?? p.name) === sourceKey)
392
+ // No entry of its own: a binding without a default reads the prop itself.
393
+ if (!param) return constant.parsed?.kind === 'member' ? declared : UNKNOWN_FACTS
394
+ return destructuredFacts(declared, param.parsed, param.defaultValue !== undefined, typed)
395
+ }
396
+
397
+ /**
398
+ * Type the props. With a props object (`function C(props)`), every default
399
+ * a `propsParams` entry carries comes from a body destructure
400
+ * (`const { label: text = 'x' } = props`): it types the local binding (a
401
+ * local constant), never `props.<key>`, which keeps its declared facts. A
402
+ * renamed body destructure (`sourceName`) never replaces the original
403
+ * property's entry. Without one, the props are destructured bindings, read
404
+ * bare and as `props.<key>`, and a default applies to both.
405
+ */
406
+ function collectPropFacts(metadata: TypingMetadata, names: Map<string, OperandFacts>, props: Map<string, OperandFacts>): void {
407
+ const propsObject = metadata.propsObjectName ?? null
408
+ for (const param of metadata.propsParams) {
409
+ const key = param.sourceName ?? param.name
410
+ if (propsObject) {
411
+ if (param.sourceName === undefined || !props.has(key)) props.set(key, declaredPropFacts(param))
412
+ continue
413
+ }
414
+ const facts = boundPropFacts(param, { names, props, propsObject })
415
+ props.set(key, facts)
416
+ names.set(param.name, facts)
417
+ }
418
+ }
419
+
420
+ /**
421
+ * A signal's facts: its declared type or literal seed, and the nil its seed
422
+ * is (`createSignal<number>()` and `createSignal<number | null>(null)` start
423
+ * nil). The SSR read is the seed.
424
+ */
425
+ function signalFacts(signal: TypingMetadata['signals'][number]): OperandFacts {
426
+ const facts = declaredOrSeeded(signal.type, signal.parsed)
427
+ if (signal.initialValue.trim() === '') return withNil(facts, 'undefined')
428
+ const seed = factsOfLiteral(signal.parsed)
429
+ return seed?.nil === undefined ? facts : withNil(facts, seed.nil === 'null' ? 'null' : 'undefined')
430
+ }
431
+
432
+ /**
433
+ * Build the component's {@link OperandTyping} from its metadata. Bare names
434
+ * hold signal getters, memos, local constants and (only when the props are
435
+ * destructured) the props; `props.<key>` reads hold the props by their
436
+ * caller-facing key. A later source shadows an earlier one of the same name,
437
+ * so a local constant shadows a destructured prop.
438
+ *
439
+ * Unlike `collectNumberValueNames` and the adapters' `collectStringValueNames`,
440
+ * an optional prop without a default is not proven its declared type: an
441
+ * omitted prop reads nil (`undefined`).
442
+ */
443
+ export function collectOperandTyping(metadata: TypingMetadata, options: OperandTypingOptions = {}): OperandTyping {
444
+ const names = new Map<string, OperandFacts>()
445
+ const props = new Map<string, OperandFacts>()
446
+ collectPropFacts(metadata, names, props)
447
+ for (const signal of metadata.signals) names.set(signal.getter, signalFacts(signal))
448
+ for (const memo of metadata.memos ?? []) names.set(memo.name, factsOfType(memo.type))
449
+ const typed: TypedNames = { names, props, propsObject: metadata.propsObjectName ?? null }
450
+ for (const constant of metadata.localConstants ?? []) {
451
+ names.set(constant.name, constantFacts(constant, metadata.propsParams, typed))
452
+ }
453
+ const namedFields: NamedTypeFields =
454
+ options.namedFields ?? (typeName => metadata.typeDefinitions?.find(td => td.name === typeName)?.properties)
455
+ return {
456
+ at: scope => scopedTyping(scope, names, props, namedFields),
457
+ }
458
+ }
459
+
460
+ /** An {@link OperandTyping} proving nothing about any outer name; loop bindings still type. */
461
+ export const EMPTY_OPERAND_TYPING: OperandTyping = {
462
+ at: scope => scopedTyping(scope, new Map(), new Map(), () => undefined),
463
+ }
464
+
465
+ function scopedTyping(
466
+ scope: BindingScope,
467
+ names: ReadonlyMap<string, OperandFacts>,
468
+ props: ReadonlyMap<string, OperandFacts>,
469
+ namedFields: NamedTypeFields,
470
+ ): ScopedOperandTyping {
471
+ const typing: ScopedOperandTyping = {
472
+ scope,
473
+ name: name => {
474
+ const hit = scope.lookup(name)
475
+ return hit ? bindingFacts(hit.binding, [], namedFields) : (names.get(name) ?? UNKNOWN_FACTS)
476
+ },
477
+ prop: key => {
478
+ // A binding named `props` reads its own member (#3693); in a component
479
+ // whose props object has another name, an unbound `props` is nothing.
480
+ if (scope.isBound(PROPS_OBJECT_IDENTIFIER)) return typing.path(PROPS_OBJECT_IDENTIFIER, [key])
481
+ if (scope.propsObject !== PROPS_OBJECT_IDENTIFIER) return UNKNOWN_FACTS
482
+ return props.get(key) ?? UNKNOWN_FACTS
483
+ },
484
+ path: (root, path) => {
485
+ if (path.length === 0) return typing.name(root)
486
+ // An outer name's typing covers the name itself, not a member of it.
487
+ const hit = scope.lookup(root)
488
+ return hit ? bindingFacts(hit.binding, path, namedFields) : UNKNOWN_FACTS
489
+ },
490
+ enterCallback: params => scopedTyping(scope.enterCallback([...params]), names, props, namedFields),
491
+ }
492
+ return typing
493
+ }
494
+
495
+ /** What a read of a loop / callback binding (and a field path below it) proves. */
496
+ function bindingFacts(binding: ScopeBinding, path: readonly string[], namedFields: NamedTypeFields): OperandFacts {
497
+ if (path.length === 0 && binding.source === 'index') return { types: new Set<OperandType>(['number']), index: true }
498
+ if (path.length === 0 && binding.stringValue === true) return factsOf('string')
499
+ if (!binding.row) return UNKNOWN_FACTS
500
+ const segments = [...binding.row.segments, ...path.map(key => ({ kind: 'field' as const, key, isIdent: true }))]
501
+ return factsOfType(loopValueTypeAt(binding.row.itemType, segments, namedFields))
502
+ }
503
+
504
+ /**
505
+ * An {@link OperandTyping}-shaped view over name tests, for the legacy
506
+ * classifiers that take a callback instead of a typing (`isBooleanResultParsed`'s
507
+ * `isBooleanName`). A name the test accepts is proven `type`; nothing else is.
508
+ */
509
+ export function typingFromNameTest(
510
+ type: 'boolean' | 'string' | 'number',
511
+ test: ((name: string, componentProperty?: boolean) => boolean) | undefined,
512
+ ): ScopedOperandTyping {
513
+ const proven = factsOf(type)
514
+ const typing: ScopedOperandTyping = {
515
+ scope: BindingScope.EMPTY,
516
+ name: name => (test?.(name) ? proven : UNKNOWN_FACTS),
517
+ prop: key => (test?.(key, true) ? proven : UNKNOWN_FACTS),
518
+ path: (root, path) => (path.length === 0 && test?.(root) ? proven : UNKNOWN_FACTS),
519
+ enterCallback: () => typing,
520
+ }
521
+ return typing
522
+ }