market-feed 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # market-feed Changelog
 
+## 1.0.0 — 2026-03-12
+
+### New module
+
+**`market-feed/react`** — React hooks for live market data. Requires React ≥ 18.
+
+```tsx
+import { useQuote, useStream, useAlerts } from "market-feed/react";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+
+// Poll a single quote
+function StockPrice({ symbol }: { symbol: string }) {
+  const { data, loading, error } = useQuote(feed, symbol);
+  if (loading) return <span>…</span>;
+  if (error) return <span>Error: {error.message}</span>;
+  return <span>{symbol}: ${data?.price.toFixed(2)}</span>;
+}
+
+// Subscribe to a live stream
+function LiveFeed() {
+  const { event } = useStream(feed, ["AAPL", "MSFT", "GOOGL"]);
+  if (!event || event.type !== "quote") return null;
+  return <p>{event.symbol}: ${event.quote.price}</p>;
+}
+
+// Collect price alerts
+function AlertLog() {
+  const { events, clearEvents } = useAlerts(feed, [
+    { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: false },
+  ]);
+  return (
+    <ul>
+      {events.map((e, i) => <li key={i}>{e.alert.symbol} triggered @ ${e.quote.price}</li>)}
+      <button onClick={clearEvents}>Clear</button>
+    </ul>
+  );
+}
+```
+
+#### Hook reference
+
+**`useQuote(source, symbol, options?)`**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `intervalMs` | `5000` | Poll interval in milliseconds |
+| `enabled` | `true` | Set to `false` to suspend polling |
+
+Returns `{ data: Quote \| null, loading: boolean, error: Error \| null, refetch() }`.
+
+**`useStream(feed, symbols, options?)`**
+
+Drives a `watch()` async generator. Restarts automatically when `symbols` changes. Stops on unmount via an internal `AbortSignal`.
+
+Returns `{ event: StreamEvent \| null, error: Error \| null }`.
+
+**`useAlerts(feed, alerts, options?)`**
+
+Drives a `watchAlerts()` async generator. Restarts when alert definitions (symbol + condition type + threshold) change.
+
+Returns `{ events: AlertEvent[], error: Error \| null, clearEvents() }`.
+
+#### Note on peer dependency
+
+`react` is a peer dependency — install it separately in your project:
+
+```
+npm install react
+```
+
+---
+
+## 0.9.0 — 2026-03-12
+
+### New module
+
+**`market-feed/screener`** — Filter a list of symbols against a set of criteria using live quote data.
+
+```ts
+import { screen } from "market-feed/screener";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+
+const results = await screen(feed, ["AAPL", "MSFT", "GOOGL", "TSLA", "NVDA"], {
+  criteria: [
+    { type: "price_above", value: 100 },
+    { type: "change_pct_above", value: 1.5 },
+    { type: "volume_above", value: 10_000_000 },
+    { type: "market_cap_above", value: 100_000_000_000 },
+  ],
+  limit: 10,
+});
+
+console.log(results.map((r) => `${r.symbol} @ ${r.quote.price}`));
+```
+
+#### Criterion types
+
+| Type | Description |
+|------|-------------|
+| `price_above` / `price_below` | Filter by current price |
+| `change_pct_above` / `change_pct_below` | Filter by daily % change |
+| `volume_above` / `volume_below` | Filter by trading volume |
+| `market_cap_above` / `market_cap_below` | Filter by market cap |
+| `52w_high_pct_below` | Price is within N% of the 52-week high |
+| `52w_low_pct_above` | Price is at least N% above the 52-week low |
+| `custom` | Arbitrary predicate: `{ type: "custom", fn: (quote) => boolean }` |
+
+All criteria are evaluated with **AND logic** — a symbol must pass every criterion to be included.
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `criteria` | Array of `ScreenerCriterion` (required) |
+| `batchSize` | Max symbols per quote fetch call (default: all at once) |
+| `limit` | Max number of results to return |
+
+#### Result shape
+
+```ts
+interface ScreenerResult {
+  symbol: string;
+  quote: Quote;
+  matchedCriteria: number; // always === criteria.length
+}
+```
+
+`screen()` accepts any object with a `quote(symbols[]) → Quote[]` method — works with `MarketFeed`, individual providers, or your own mock.
+
+---
+
 ## 0.8.0 — 2026-03-12
 
 ### New module

package/dist/alerts.d.cts

@@ -1,44 +1,6 @@
 import { a as Quote } from './quote-Cfh_7Cgg.cjs';
-
-type AlertCondition = {
-    type: "price_above";
-    threshold: number;
-} | {
-    type: "price_below";
-    threshold: number;
-} | {
-    type: "change_pct_above";
-    threshold: number;
-} | {
-    type: "change_pct_below";
-    threshold: number;
-} | {
-    type: "volume_above";
-    threshold: number;
-};
-interface AlertConfig {
-    symbol: string;
-    condition: AlertCondition;
-    /** Emit this alert at most once, then stop watching it. Defaults to false. */
-    once?: boolean;
-    /**
-     * Suppress re-fires within this many milliseconds after the last trigger.
-     * Defaults to 0 (no debounce).
-     */
-    debounceMs?: number;
-}
-interface AlertEvent {
-    type: "triggered";
-    alert: AlertConfig;
-    quote: Quote;
-    triggeredAt: Date;
-}
-interface AlertsOptions {
-    /** Poll interval in milliseconds. Defaults to 5 000. */
-    intervalMs?: number;
-    /** AbortSignal to stop the generator. */
-    signal?: AbortSignal;
-}
+import { A as AlertConfig, a as AlertsOptions, b as AlertEvent } from './types-hzOO9Cst.cjs';
+export { c as AlertCondition } from './types-hzOO9Cst.cjs';
 
 interface QuoteFetcher {
     quote(symbols: string[]): Promise<Quote[]>;
@@ -67,4 +29,4 @@ interface QuoteFetcher {
  */
 declare function watchAlerts(feed: QuoteFetcher, alerts: AlertConfig[], options?: AlertsOptions): AsyncGenerator<AlertEvent>;
 
-export { type AlertCondition, type AlertConfig, type AlertEvent, type AlertsOptions, watchAlerts };
+export { AlertConfig, AlertEvent, AlertsOptions, watchAlerts };

package/dist/alerts.d.ts

@@ -1,44 +1,6 @@
 import { a as Quote } from './quote-Cfh_7Cgg.js';
-
-type AlertCondition = {
-    type: "price_above";
-    threshold: number;
-} | {
-    type: "price_below";
-    threshold: number;
-} | {
-    type: "change_pct_above";
-    threshold: number;
-} | {
-    type: "change_pct_below";
-    threshold: number;
-} | {
-    type: "volume_above";
-    threshold: number;
-};
-interface AlertConfig {
-    symbol: string;
-    condition: AlertCondition;
-    /** Emit this alert at most once, then stop watching it. Defaults to false. */
-    once?: boolean;
-    /**
-     * Suppress re-fires within this many milliseconds after the last trigger.
-     * Defaults to 0 (no debounce).
-     */
-    debounceMs?: number;
-}
-interface AlertEvent {
-    type: "triggered";
-    alert: AlertConfig;
-    quote: Quote;
-    triggeredAt: Date;
-}
-interface AlertsOptions {
-    /** Poll interval in milliseconds. Defaults to 5 000. */
-    intervalMs?: number;
-    /** AbortSignal to stop the generator. */
-    signal?: AbortSignal;
-}
+import { A as AlertConfig, a as AlertsOptions, b as AlertEvent } from './types-D90J5xwU.js';
+export { c as AlertCondition } from './types-D90J5xwU.js';
 
 interface QuoteFetcher {
     quote(symbols: string[]): Promise<Quote[]>;
@@ -67,4 +29,4 @@ interface QuoteFetcher {
  */
 declare function watchAlerts(feed: QuoteFetcher, alerts: AlertConfig[], options?: AlertsOptions): AsyncGenerator<AlertEvent>;
 
-export { type AlertCondition, type AlertConfig, type AlertEvent, type AlertsOptions, watchAlerts };
+export { AlertConfig, AlertEvent, AlertsOptions, watchAlerts };