market-feed 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # market-feed Changelog
 
+## 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/screener.cjs

@@ -0,0 +1,76 @@
+'use strict';
+
+// market-feed — Unified financial market data client
+// https://github.com/piyushgupta344/market-feed
+
+// src/screener/index.ts
+async function screen(source, symbols, options) {
+  if (symbols.length === 0 || options.criteria.length === 0) return [];
+  const { criteria, batchSize, limit } = options;
+  const quotes = await fetchInBatches(source, symbols, batchSize);
+  const results = [];
+  for (const quote of quotes) {
+    if (matchesAll(quote, criteria)) {
+      results.push({ symbol: quote.symbol, quote, matchedCriteria: criteria.length });
+      if (limit !== void 0 && results.length >= limit) break;
+    }
+  }
+  return results;
+}
+function matchesAll(quote, criteria) {
+  for (const c of criteria) {
+    if (!matchesCriterion(quote, c)) return false;
+  }
+  return true;
+}
+function matchesCriterion(quote, criterion) {
+  switch (criterion.type) {
+    case "price_above":
+      return quote.price > criterion.value;
+    case "price_below":
+      return quote.price < criterion.value;
+    case "change_pct_above":
+      return quote.changePercent > criterion.value;
+    case "change_pct_below":
+      return quote.changePercent < criterion.value;
+    case "volume_above":
+      return quote.volume > criterion.value;
+    case "volume_below":
+      return quote.volume < criterion.value;
+    case "market_cap_above":
+      return quote.marketCap !== void 0 && quote.marketCap > criterion.value;
+    case "market_cap_below":
+      return quote.marketCap !== void 0 && quote.marketCap < criterion.value;
+    case "pe_above":
+      return true;
+    case "pe_below":
+      return true;
+    case "52w_high_pct_below": {
+      if (quote.fiftyTwoWeekHigh === void 0) return true;
+      const pctBelow = (quote.fiftyTwoWeekHigh - quote.price) / quote.fiftyTwoWeekHigh * 100;
+      return pctBelow < criterion.value;
+    }
+    case "52w_low_pct_above": {
+      if (quote.fiftyTwoWeekLow === void 0) return true;
+      const pctAbove = (quote.price - quote.fiftyTwoWeekLow) / quote.fiftyTwoWeekLow * 100;
+      return pctAbove > criterion.value;
+    }
+    case "custom":
+      return criterion.fn(quote);
+  }
+}
+async function fetchInBatches(source, symbols, batchSize) {
+  if (!batchSize || batchSize >= symbols.length) {
+    return source.quote(symbols);
+  }
+  const batches = [];
+  for (let i = 0; i < symbols.length; i += batchSize) {
+    batches.push(symbols.slice(i, i + batchSize));
+  }
+  const results = await Promise.all(batches.map((batch) => source.quote(batch)));
+  return results.flat();
+}
+
+exports.screen = screen;
+//# sourceMappingURL=screener.cjs.map
+//# sourceMappingURL=screener.cjs.map

package/dist/screener.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/screener/index.ts"],"names":[],"mappings":"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","file":"screener.cjs","sourcesContent":["/**\n * market-feed/screener\n *\n * Filter a list of symbols against a set of criteria using live quote data,\n * company profile data, or any custom condition function.\n *\n * @example\n * ```ts\n * import { screen } from \"market-feed/screener\";\n * import { MarketFeed } from \"market-feed\";\n *\n * const feed = new MarketFeed();\n *\n * const results = await screen(feed, [\"AAPL\", \"MSFT\", \"GOOGL\", \"TSLA\"], {\n *   criteria: [\n *     { type: \"price_above\", value: 100 },\n *     { type: \"change_pct_above\", value: -5 },\n *     { type: \"volume_above\", value: 1_000_000 },\n *   ],\n * });\n *\n * console.log(results.map((r) => r.symbol));\n * ```\n */\n\nimport type { Quote } from \"../types/quote.js\";\n\n// ---------------------------------------------------------------------------\n// Criterion types\n// ---------------------------------------------------------------------------\n\nexport type QuoteCriterion =\n  | { type: \"price_above\"; value: number }\n  | { type: \"price_below\"; value: number }\n  | { type: \"change_pct_above\"; value: number }\n  | { type: \"change_pct_below\"; value: number }\n  | { type: \"volume_above\"; value: number }\n  | { type: \"volume_below\"; value: number }\n  | { type: \"market_cap_above\"; value: number }\n  | { type: \"market_cap_below\"; value: number }\n  | { type: \"pe_above\"; value: number }\n  | { type: \"pe_below\"; value: number }\n  | { type: \"52w_high_pct_below\"; value: number }\n  | { type: \"52w_low_pct_above\"; value: number }\n  /** Custom predicate — return true to include, false to exclude */\n  | { type: \"custom\"; fn: (quote: Quote) => boolean };\n\nexport type ScreenerCriterion = QuoteCriterion;\n\nexport interface ScreenerOptions {\n  /** List of criteria — ALL must pass (logical AND) */\n  criteria: ScreenerCriterion[];\n  /**\n   * Maximum number of symbols to fetch quotes for per batch.\n   * Defaults to all symbols in one call.\n   */\n  batchSize?: number;\n  /**\n   * Maximum number of results to return.\n   * Defaults to all matching symbols.\n   */\n  limit?: number;\n}\n\nexport interface ScreenerResult {\n  symbol: string;\n  quote: Quote;\n  /** Which criteria matched (all of them, by design) */\n  matchedCriteria: number;\n}\n\n// ---------------------------------------------------------------------------\n// Quote source interface (duck-typed for testability)\n// ---------------------------------------------------------------------------\n\ninterface QuoteSource {\n  quote(symbols: string[], options?: { raw?: boolean }): Promise<Quote[]>;\n}\n\n// ---------------------------------------------------------------------------\n// Core screener function\n// ---------------------------------------------------------------------------\n\n/**\n * Screen a list of symbols against a set of criteria.\n *\n * Fetches quotes for all symbols (in optional batches) and returns those\n * that satisfy ALL of the provided criteria.\n *\n * @param source - Any object with a `quote(symbols[]) → Quote[]` method (e.g. `MarketFeed`, a single provider)\n * @param symbols - Symbols to evaluate\n * @param options - Screener configuration\n */\nexport async function screen(\n  source: QuoteSource,\n  symbols: string[],\n  options: ScreenerOptions,\n): Promise<ScreenerResult[]> {\n  if (symbols.length === 0 || options.criteria.length === 0) return [];\n\n  const { criteria, batchSize, limit } = options;\n\n  // Fetch quotes in batches (or all at once if no batchSize)\n  const quotes = await fetchInBatches(source, symbols, batchSize);\n\n  const results: ScreenerResult[] = [];\n  for (const quote of quotes) {\n    if (matchesAll(quote, criteria)) {\n      results.push({ symbol: quote.symbol, quote, matchedCriteria: criteria.length });\n      if (limit !== undefined && results.length >= limit) break;\n    }\n  }\n\n  return results;\n}\n\n// ---------------------------------------------------------------------------\n// Criterion evaluator\n// ---------------------------------------------------------------------------\n\nfunction matchesAll(quote: Quote, criteria: ScreenerCriterion[]): boolean {\n  for (const c of criteria) {\n    if (!matchesCriterion(quote, c)) return false;\n  }\n  return true;\n}\n\nfunction matchesCriterion(quote: Quote, criterion: ScreenerCriterion): boolean {\n  switch (criterion.type) {\n    case \"price_above\":\n      return quote.price > criterion.value;\n    case \"price_below\":\n      return quote.price < criterion.value;\n    case \"change_pct_above\":\n      return quote.changePercent > criterion.value;\n    case \"change_pct_below\":\n      return quote.changePercent < criterion.value;\n    case \"volume_above\":\n      return quote.volume > criterion.value;\n    case \"volume_below\":\n      return quote.volume < criterion.value;\n    case \"market_cap_above\":\n      return quote.marketCap !== undefined && quote.marketCap > criterion.value;\n    case \"market_cap_below\":\n      return quote.marketCap !== undefined && quote.marketCap < criterion.value;\n    case \"pe_above\":\n      // CompanyProfile-level data is not on Quote — skip (return true to not block)\n      return true;\n    case \"pe_below\":\n      return true;\n    case \"52w_high_pct_below\": {\n      if (quote.fiftyTwoWeekHigh === undefined) return true;\n      const pctBelow = ((quote.fiftyTwoWeekHigh - quote.price) / quote.fiftyTwoWeekHigh) * 100;\n      return pctBelow < criterion.value;\n    }\n    case \"52w_low_pct_above\": {\n      if (quote.fiftyTwoWeekLow === undefined) return true;\n      const pctAbove = ((quote.price - quote.fiftyTwoWeekLow) / quote.fiftyTwoWeekLow) * 100;\n      return pctAbove > criterion.value;\n    }\n    case \"custom\":\n      return criterion.fn(quote);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Batch fetching helper\n// ---------------------------------------------------------------------------\n\nasync function fetchInBatches(\n  source: QuoteSource,\n  symbols: string[],\n  batchSize?: number,\n): Promise<Quote[]> {\n  if (!batchSize || batchSize >= symbols.length) {\n    return source.quote(symbols);\n  }\n\n  const batches: string[][] = [];\n  for (let i = 0; i < symbols.length; i += batchSize) {\n    batches.push(symbols.slice(i, i + batchSize));\n  }\n\n  const results = await Promise.all(batches.map((batch) => source.quote(batch)));\n  return results.flat();\n}\n"]}

package/dist/screener.d.cts

@@ -0,0 +1,108 @@
+import { a as Quote } from './quote-Cfh_7Cgg.cjs';
+
+/**
+ * market-feed/screener
+ *
+ * Filter a list of symbols against a set of criteria using live quote data,
+ * company profile data, or any custom condition function.
+ *
+ * @example
+ * ```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"], {
+ *   criteria: [
+ *     { type: "price_above", value: 100 },
+ *     { type: "change_pct_above", value: -5 },
+ *     { type: "volume_above", value: 1_000_000 },
+ *   ],
+ * });
+ *
+ * console.log(results.map((r) => r.symbol));
+ * ```
+ */
+
+type QuoteCriterion = {
+    type: "price_above";
+    value: number;
+} | {
+    type: "price_below";
+    value: number;
+} | {
+    type: "change_pct_above";
+    value: number;
+} | {
+    type: "change_pct_below";
+    value: number;
+} | {
+    type: "volume_above";
+    value: number;
+} | {
+    type: "volume_below";
+    value: number;
+} | {
+    type: "market_cap_above";
+    value: number;
+} | {
+    type: "market_cap_below";
+    value: number;
+} | {
+    type: "pe_above";
+    value: number;
+} | {
+    type: "pe_below";
+    value: number;
+} | {
+    type: "52w_high_pct_below";
+    value: number;
+} | {
+    type: "52w_low_pct_above";
+    value: number;
+}
+/** Custom predicate — return true to include, false to exclude */
+ | {
+    type: "custom";
+    fn: (quote: Quote) => boolean;
+};
+type ScreenerCriterion = QuoteCriterion;
+interface ScreenerOptions {
+    /** List of criteria — ALL must pass (logical AND) */
+    criteria: ScreenerCriterion[];
+    /**
+     * Maximum number of symbols to fetch quotes for per batch.
+     * Defaults to all symbols in one call.
+     */
+    batchSize?: number;
+    /**
+     * Maximum number of results to return.
+     * Defaults to all matching symbols.
+     */
+    limit?: number;
+}
+interface ScreenerResult {
+    symbol: string;
+    quote: Quote;
+    /** Which criteria matched (all of them, by design) */
+    matchedCriteria: number;
+}
+interface QuoteSource {
+    quote(symbols: string[], options?: {
+        raw?: boolean;
+    }): Promise<Quote[]>;
+}
+/**
+ * Screen a list of symbols against a set of criteria.
+ *
+ * Fetches quotes for all symbols (in optional batches) and returns those
+ * that satisfy ALL of the provided criteria.
+ *
+ * @param source - Any object with a `quote(symbols[]) → Quote[]` method (e.g. `MarketFeed`, a single provider)
+ * @param symbols - Symbols to evaluate
+ * @param options - Screener configuration
+ */
+declare function screen(source: QuoteSource, symbols: string[], options: ScreenerOptions): Promise<ScreenerResult[]>;
+
+export { type QuoteCriterion, type ScreenerCriterion, type ScreenerOptions, type ScreenerResult, screen };

package/dist/screener.d.ts

@@ -0,0 +1,108 @@
+import { a as Quote } from './quote-Cfh_7Cgg.js';
+
+/**
+ * market-feed/screener
+ *
+ * Filter a list of symbols against a set of criteria using live quote data,
+ * company profile data, or any custom condition function.
+ *
+ * @example
+ * ```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"], {
+ *   criteria: [
+ *     { type: "price_above", value: 100 },
+ *     { type: "change_pct_above", value: -5 },
+ *     { type: "volume_above", value: 1_000_000 },
+ *   ],
+ * });
+ *
+ * console.log(results.map((r) => r.symbol));
+ * ```
+ */
+
+type QuoteCriterion = {
+    type: "price_above";
+    value: number;
+} | {
+    type: "price_below";
+    value: number;
+} | {
+    type: "change_pct_above";
+    value: number;
+} | {
+    type: "change_pct_below";
+    value: number;
+} | {
+    type: "volume_above";
+    value: number;
+} | {
+    type: "volume_below";
+    value: number;
+} | {
+    type: "market_cap_above";
+    value: number;
+} | {
+    type: "market_cap_below";
+    value: number;
+} | {
+    type: "pe_above";
+    value: number;
+} | {
+    type: "pe_below";
+    value: number;
+} | {
+    type: "52w_high_pct_below";
+    value: number;
+} | {
+    type: "52w_low_pct_above";
+    value: number;
+}
+/** Custom predicate — return true to include, false to exclude */
+ | {
+    type: "custom";
+    fn: (quote: Quote) => boolean;
+};
+type ScreenerCriterion = QuoteCriterion;
+interface ScreenerOptions {
+    /** List of criteria — ALL must pass (logical AND) */
+    criteria: ScreenerCriterion[];
+    /**
+     * Maximum number of symbols to fetch quotes for per batch.
+     * Defaults to all symbols in one call.
+     */
+    batchSize?: number;
+    /**
+     * Maximum number of results to return.
+     * Defaults to all matching symbols.
+     */
+    limit?: number;
+}
+interface ScreenerResult {
+    symbol: string;
+    quote: Quote;
+    /** Which criteria matched (all of them, by design) */
+    matchedCriteria: number;
+}
+interface QuoteSource {
+    quote(symbols: string[], options?: {
+        raw?: boolean;
+    }): Promise<Quote[]>;
+}
+/**
+ * Screen a list of symbols against a set of criteria.
+ *
+ * Fetches quotes for all symbols (in optional batches) and returns those
+ * that satisfy ALL of the provided criteria.
+ *
+ * @param source - Any object with a `quote(symbols[]) → Quote[]` method (e.g. `MarketFeed`, a single provider)
+ * @param symbols - Symbols to evaluate
+ * @param options - Screener configuration
+ */
+declare function screen(source: QuoteSource, symbols: string[], options: ScreenerOptions): Promise<ScreenerResult[]>;
+
+export { type QuoteCriterion, type ScreenerCriterion, type ScreenerOptions, type ScreenerResult, screen };

package/dist/screener.js

@@ -0,0 +1,74 @@
+// market-feed — Unified financial market data client
+// https://github.com/piyushgupta344/market-feed
+
+// src/screener/index.ts
+async function screen(source, symbols, options) {
+  if (symbols.length === 0 || options.criteria.length === 0) return [];
+  const { criteria, batchSize, limit } = options;
+  const quotes = await fetchInBatches(source, symbols, batchSize);
+  const results = [];
+  for (const quote of quotes) {
+    if (matchesAll(quote, criteria)) {
+      results.push({ symbol: quote.symbol, quote, matchedCriteria: criteria.length });
+      if (limit !== void 0 && results.length >= limit) break;
+    }
+  }
+  return results;
+}
+function matchesAll(quote, criteria) {
+  for (const c of criteria) {
+    if (!matchesCriterion(quote, c)) return false;
+  }
+  return true;
+}
+function matchesCriterion(quote, criterion) {
+  switch (criterion.type) {
+    case "price_above":
+      return quote.price > criterion.value;
+    case "price_below":
+      return quote.price < criterion.value;
+    case "change_pct_above":
+      return quote.changePercent > criterion.value;
+    case "change_pct_below":
+      return quote.changePercent < criterion.value;
+    case "volume_above":
+      return quote.volume > criterion.value;
+    case "volume_below":
+      return quote.volume < criterion.value;
+    case "market_cap_above":
+      return quote.marketCap !== void 0 && quote.marketCap > criterion.value;
+    case "market_cap_below":
+      return quote.marketCap !== void 0 && quote.marketCap < criterion.value;
+    case "pe_above":
+      return true;
+    case "pe_below":
+      return true;
+    case "52w_high_pct_below": {
+      if (quote.fiftyTwoWeekHigh === void 0) return true;
+      const pctBelow = (quote.fiftyTwoWeekHigh - quote.price) / quote.fiftyTwoWeekHigh * 100;
+      return pctBelow < criterion.value;
+    }
+    case "52w_low_pct_above": {
+      if (quote.fiftyTwoWeekLow === void 0) return true;
+      const pctAbove = (quote.price - quote.fiftyTwoWeekLow) / quote.fiftyTwoWeekLow * 100;
+      return pctAbove > criterion.value;
+    }
+    case "custom":
+      return criterion.fn(quote);
+  }
+}
+async function fetchInBatches(source, symbols, batchSize) {
+  if (!batchSize || batchSize >= symbols.length) {
+    return source.quote(symbols);
+  }
+  const batches = [];
+  for (let i = 0; i < symbols.length; i += batchSize) {
+    batches.push(symbols.slice(i, i + batchSize));
+  }
+  const results = await Promise.all(batches.map((batch) => source.quote(batch)));
+  return results.flat();
+}
+
+export { screen };
+//# sourceMappingURL=screener.js.map
+//# sourceMappingURL=screener.js.map

package/dist/screener.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/screener/index.ts"],"names":[],"mappings":"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","file":"screener.js","sourcesContent":["/**\n * market-feed/screener\n *\n * Filter a list of symbols against a set of criteria using live quote data,\n * company profile data, or any custom condition function.\n *\n * @example\n * ```ts\n * import { screen } from \"market-feed/screener\";\n * import { MarketFeed } from \"market-feed\";\n *\n * const feed = new MarketFeed();\n *\n * const results = await screen(feed, [\"AAPL\", \"MSFT\", \"GOOGL\", \"TSLA\"], {\n *   criteria: [\n *     { type: \"price_above\", value: 100 },\n *     { type: \"change_pct_above\", value: -5 },\n *     { type: \"volume_above\", value: 1_000_000 },\n *   ],\n * });\n *\n * console.log(results.map((r) => r.symbol));\n * ```\n */\n\nimport type { Quote } from \"../types/quote.js\";\n\n// ---------------------------------------------------------------------------\n// Criterion types\n// ---------------------------------------------------------------------------\n\nexport type QuoteCriterion =\n  | { type: \"price_above\"; value: number }\n  | { type: \"price_below\"; value: number }\n  | { type: \"change_pct_above\"; value: number }\n  | { type: \"change_pct_below\"; value: number }\n  | { type: \"volume_above\"; value: number }\n  | { type: \"volume_below\"; value: number }\n  | { type: \"market_cap_above\"; value: number }\n  | { type: \"market_cap_below\"; value: number }\n  | { type: \"pe_above\"; value: number }\n  | { type: \"pe_below\"; value: number }\n  | { type: \"52w_high_pct_below\"; value: number }\n  | { type: \"52w_low_pct_above\"; value: number }\n  /** Custom predicate — return true to include, false to exclude */\n  | { type: \"custom\"; fn: (quote: Quote) => boolean };\n\nexport type ScreenerCriterion = QuoteCriterion;\n\nexport interface ScreenerOptions {\n  /** List of criteria — ALL must pass (logical AND) */\n  criteria: ScreenerCriterion[];\n  /**\n   * Maximum number of symbols to fetch quotes for per batch.\n   * Defaults to all symbols in one call.\n   */\n  batchSize?: number;\n  /**\n   * Maximum number of results to return.\n   * Defaults to all matching symbols.\n   */\n  limit?: number;\n}\n\nexport interface ScreenerResult {\n  symbol: string;\n  quote: Quote;\n  /** Which criteria matched (all of them, by design) */\n  matchedCriteria: number;\n}\n\n// ---------------------------------------------------------------------------\n// Quote source interface (duck-typed for testability)\n// ---------------------------------------------------------------------------\n\ninterface QuoteSource {\n  quote(symbols: string[], options?: { raw?: boolean }): Promise<Quote[]>;\n}\n\n// ---------------------------------------------------------------------------\n// Core screener function\n// ---------------------------------------------------------------------------\n\n/**\n * Screen a list of symbols against a set of criteria.\n *\n * Fetches quotes for all symbols (in optional batches) and returns those\n * that satisfy ALL of the provided criteria.\n *\n * @param source - Any object with a `quote(symbols[]) → Quote[]` method (e.g. `MarketFeed`, a single provider)\n * @param symbols - Symbols to evaluate\n * @param options - Screener configuration\n */\nexport async function screen(\n  source: QuoteSource,\n  symbols: string[],\n  options: ScreenerOptions,\n): Promise<ScreenerResult[]> {\n  if (symbols.length === 0 || options.criteria.length === 0) return [];\n\n  const { criteria, batchSize, limit } = options;\n\n  // Fetch quotes in batches (or all at once if no batchSize)\n  const quotes = await fetchInBatches(source, symbols, batchSize);\n\n  const results: ScreenerResult[] = [];\n  for (const quote of quotes) {\n    if (matchesAll(quote, criteria)) {\n      results.push({ symbol: quote.symbol, quote, matchedCriteria: criteria.length });\n      if (limit !== undefined && results.length >= limit) break;\n    }\n  }\n\n  return results;\n}\n\n// ---------------------------------------------------------------------------\n// Criterion evaluator\n// ---------------------------------------------------------------------------\n\nfunction matchesAll(quote: Quote, criteria: ScreenerCriterion[]): boolean {\n  for (const c of criteria) {\n    if (!matchesCriterion(quote, c)) return false;\n  }\n  return true;\n}\n\nfunction matchesCriterion(quote: Quote, criterion: ScreenerCriterion): boolean {\n  switch (criterion.type) {\n    case \"price_above\":\n      return quote.price > criterion.value;\n    case \"price_below\":\n      return quote.price < criterion.value;\n    case \"change_pct_above\":\n      return quote.changePercent > criterion.value;\n    case \"change_pct_below\":\n      return quote.changePercent < criterion.value;\n    case \"volume_above\":\n      return quote.volume > criterion.value;\n    case \"volume_below\":\n      return quote.volume < criterion.value;\n    case \"market_cap_above\":\n      return quote.marketCap !== undefined && quote.marketCap > criterion.value;\n    case \"market_cap_below\":\n      return quote.marketCap !== undefined && quote.marketCap < criterion.value;\n    case \"pe_above\":\n      // CompanyProfile-level data is not on Quote — skip (return true to not block)\n      return true;\n    case \"pe_below\":\n      return true;\n    case \"52w_high_pct_below\": {\n      if (quote.fiftyTwoWeekHigh === undefined) return true;\n      const pctBelow = ((quote.fiftyTwoWeekHigh - quote.price) / quote.fiftyTwoWeekHigh) * 100;\n      return pctBelow < criterion.value;\n    }\n    case \"52w_low_pct_above\": {\n      if (quote.fiftyTwoWeekLow === undefined) return true;\n      const pctAbove = ((quote.price - quote.fiftyTwoWeekLow) / quote.fiftyTwoWeekLow) * 100;\n      return pctAbove > criterion.value;\n    }\n    case \"custom\":\n      return criterion.fn(quote);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Batch fetching helper\n// ---------------------------------------------------------------------------\n\nasync function fetchInBatches(\n  source: QuoteSource,\n  symbols: string[],\n  batchSize?: number,\n): Promise<Quote[]> {\n  if (!batchSize || batchSize >= symbols.length) {\n    return source.quote(symbols);\n  }\n\n  const batches: string[][] = [];\n  for (let i = 0; i < symbols.length; i += batchSize) {\n    batches.push(symbols.slice(i, i + batchSize));\n  }\n\n  const results = await Promise.all(batches.map((batch) => source.quote(batch)));\n  return results.flat();\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "market-feed",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Unified TypeScript client for financial market data — wraps Yahoo Finance, Alpha Vantage, Polygon.io, and Finnhub under one consistent interface with caching, fallback, and real-time WebSocket streaming.",
   "keywords": [
     "finance",
@@ -83,6 +83,11 @@
       "types": "./dist/fundamentals.d.ts",
       "import": "./dist/fundamentals.js",
       "require": "./dist/fundamentals.cjs"
+    },
+    "./screener": {
+      "types": "./dist/screener.d.ts",
+      "import": "./dist/screener.js",
+      "require": "./dist/screener.cjs"
     }
   },
   "bin": {