@ghostry/fabricator 0.0.9 → 0.0.10

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.
@@ -144,7 +144,10 @@ function normalInv(p) {
144
144
  }
145
145
  function sample(list, stream) {
146
146
  if (0 === list.length) throw new FabricatorError.EmptyItemsError("sample", "item");
147
- const index = Math.floor(stream.next() * list.length);
147
+ const index = discreteSampler(void 0, {
148
+ min: 0,
149
+ max: list.length - 1
150
+ }, stream)();
148
151
  const item = list[index];
149
152
  return item;
150
153
  }
@@ -193,16 +196,45 @@ function assertDrawableKeyedWeights(label, outcomes, weights) {
193
196
  if (0 === drawableOutcomes(outcomes, weights).length) throw new FabricatorError.NoDrawableOutcomesError(label, "outcome");
194
197
  }
195
198
  function weighted(weights, stream, label) {
196
- let sum = 0;
197
- const weightings = weights.filter(([weight])=>isDrawable(weight)).map(([weight, item])=>[
198
- sum += weight,
199
- item
200
- ]);
201
- if (0 === weightings.length) throw new FabricatorError.NoDrawableOutcomesError(label, "outcome");
199
+ const drawable = weights.filter(([weight])=>isDrawable(weight));
200
+ if (0 === drawable.length) throw new FabricatorError.NoDrawableOutcomesError(label, "outcome");
201
+ const items = drawable.map(([, item])=>item);
202
+ const column = discreteSampler(void 0, {
203
+ min: 0,
204
+ max: items.length - 1
205
+ }, stream);
206
+ const [first] = drawable[0];
207
+ if (drawable.every(([weight])=>weight === first)) return ()=>items[column()];
208
+ const table = toAliasTable(drawable.map(([weight])=>weight));
202
209
  return ()=>{
203
- const x = stream.next() * sum;
204
- const chosen = weightings.find(([weight])=>x < weight);
205
- return chosen[1];
210
+ const i = column();
211
+ const probability = table.probability[i];
212
+ if (1 === probability) return items[i];
213
+ return items[stream.next() < probability ? i : table.alias[i]];
214
+ };
215
+ }
216
+ function toAliasTable(weights) {
217
+ const n = weights.length;
218
+ const sum = weights.reduce((total, weight)=>total + weight, 0);
219
+ const scaled = weights.map((weight)=>weight * n / sum);
220
+ const probability = new Float64Array(n);
221
+ const aliases = new Uint32Array(n);
222
+ const small = [];
223
+ const large = [];
224
+ for(let i = 0; i < n; i++)(scaled[i] < 1 ? small : large).push(i);
225
+ while(small.length > 0 && large.length > 0){
226
+ const less = small.pop();
227
+ const more = large.pop();
228
+ probability[less] = scaled[less];
229
+ aliases[less] = more;
230
+ scaled[more] = scaled[more] + scaled[less] - 1;
231
+ (scaled[more] < 1 ? small : large).push(more);
232
+ }
233
+ for (const i of large)probability[i] = 1;
234
+ for (const i of small)probability[i] = 1;
235
+ return {
236
+ probability,
237
+ alias: aliases
206
238
  };
207
239
  }
208
240
  var Distribution_Distribution;
@@ -2,4 +2,5 @@ export { Children, Kind, Meta, Produces } from "./Types.js";
2
2
  export { isPlainObject } from "./Utility/Core.js";
3
3
  export { plan, resolve } from "./Enumeration/Plan.js";
4
4
  export { defaultAlgorithm, encode, randomSalt, toRandomSource, toStream, toStreamFromTrace } from "./Random/index.js";
5
+ export { weighted } from "./Distribution/index.js";
5
6
  export { toStack as toSynchronousStack } from "./Instance/Stack/Sync.js";
@@ -134,8 +134,9 @@ export declare function isDrawable(weight: number): boolean;
134
134
  * Whether a weight is _expressible_ at all, as opposed to whether it is
135
135
  * drawable. `0` is valid and disables the outcome; a negative weight or `NaN`
136
136
  * is a mistake. `Infinity` is rejected because it cannot be summed into a
137
- * usable draw table — every cumulative bound becomes `Infinity`, so
138
- * `weighted()`'s `x < weight` scan matches nothing.
137
+ * usable draw table — the sum becomes `Infinity`, so `weighted()`'s alias
138
+ * scaling (`weight * n / sum`) yields `NaN` for the infinite entry and `0` for
139
+ * every other.
139
140
  */
140
141
  export declare function isValidWeight(weight: number): boolean;
141
142
  /**
@@ -166,4 +167,23 @@ export declare function assertDrawableWeights(label: string, noun: string, items
166
167
  * defaulted in stage 2.
167
168
  */
168
169
  export declare function assertDrawableKeyedWeights<$Outcome extends string>(label: string, outcomes: ReadonlyArray<$Outcome>, weights: Readonly<Record<string, number | undefined>>): void;
170
+ /**
171
+ * A pick over `weights`, in O(1) per call regardless of table size. The table
172
+ * is built once, here, during `new Fabricator(...)`; the returned closure is
173
+ * what `.fabricate()` calls.
174
+ *
175
+ * Two paths, chosen at construction:
176
+ *
177
+ * - **Equal weights** (every `.uniform(...)` registry, every default-weighted
178
+ * presence wrapper) need no table at all: the pick is `discreteSampler`'s
179
+ * uniform index draw, one `stream.next()` per call.
180
+ * - **Unequal weights** use Vose's alias method (see {@link toAliasTable}): draw
181
+ * a column with that same index draw, then a second `stream.next()` as a coin
182
+ * between the column's own item and its alias. The coin is a separate draw
183
+ * rather than the fractional remainder of the first, because that remainder
184
+ * keeps only `53 - log2(n)` bits, which coarsens the probabilities as the
185
+ * table grows. A column whose probability is `1` returns without drawing the
186
+ * coin; the draw count stays a pure function of the stream, so this is still
187
+ * replayable.
188
+ */
169
189
  export declare function weighted<const $Item>(weights: ReadonlyArray<readonly [number, $Item]>, stream: Stream, label: string): () => $Item;
@@ -13,9 +13,9 @@ type Weighted<$Items extends ReadonlyArray<Item>> = {
13
13
  };
14
14
  /**
15
15
  * At least one element — a `choice` with no option has nothing to draw, which
16
- * would otherwise fail inside `weighted()` (`Distribution/index.ts`) with an
17
- * opaque `TypeError` at fabricate time (weight sum is `0`, so `.find` returns
18
- * `undefined` and `chosen![1]` throws).
16
+ * would otherwise surface only as `weighted()`'s (`Distribution/index.ts`)
17
+ * generic `NoDrawableOutcomesError` at construction, naming an "outcome" rather
18
+ * than this registry's own `EmptyItemsError` for an option.
19
19
  *
20
20
  * Only a _statically_ empty tuple (a literal `[]`) is a compile error. A
21
21
  * dynamically built array — e.g. `.map()` over an `as const` array — is
@@ -14,9 +14,9 @@ type Weighted<$Items extends ReadonlyArray<Item>> = {
14
14
  };
15
15
  /**
16
16
  * At least one element — an `enum` with no member has nothing to draw, which
17
- * would otherwise fail inside `weighted()` (`Distribution/index.ts`) with an
18
- * opaque `TypeError` at fabricate time (weight sum is `0`, so `.find` returns
19
- * `undefined` and `chosen![1]` throws).
17
+ * would otherwise surface only as `weighted()`'s (`Distribution/index.ts`)
18
+ * generic `NoDrawableOutcomesError` at construction, naming an "outcome" rather
19
+ * than this registry's own `EmptyItemsError` for a member.
20
20
  *
21
21
  * Only a _statically_ empty tuple (a literal `[]`) is a compile error. A
22
22
  * dynamically built array — e.g. `.map()` over an `as const` array — is
@@ -64,6 +64,13 @@ export type { Axis, Enumerable, Pin, Resolvable } from "./Enumeration/Types";
64
64
  */
65
65
  export { defaultAlgorithm, encode, randomSalt, toRandomSource, toStream, toStreamFromTrace, } from "./Random";
66
66
  export type { Algorithm, ConstructionPins, ConstructionTrace, ConstructorOptions, Salt, Trace, } from "./Random/Types";
67
+ /**
68
+ * The shared index-selection draw every weighted kind (`enum`, `choice`,
69
+ * `boolean`, the presence wrappers) reaches through construction — exported so
70
+ * a test can measure its distribution against a raw stream, without a kind's
71
+ * registry guards or `.fabricate()` in between.
72
+ */
73
+ export { weighted } from "./Distribution";
67
74
  /**
68
75
  * The synchronous ambient carrier. `#stack` (`package.json`) selects it only
69
76
  * where there is no `node:async_hooks` — in practice a browser bundle — so on
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.9",
3
+ "version": "0.0.10",
4
4
  "license": "MIT",
5
5
  "description": "Fabricate typed data from composable schemas.",
6
6
  "keywords": [