corelib

3600000
0

Fetch status and monitor phase changes against a stub ran locally

cfg.updateValue('markets.nasdaq.statusEndpoint', `http://127.0.0.1:${port}/api/market-info`);
const st = await MarketStatus.getStatus();
console.log(st.status, st.value.mrktStatus);

const monitor = new MarketMonitor({ liveIntervalSec: 15, closedIntervalSec: 1800 });
monitor.on('status-change', (phase, data, heuristic) => {
  console.log('phase', phase, 'heuristic', !!heuristic, data.nextTradeDate);
  monitor.stop();
});
monitor.on('stopped', () => console.log('stopped; running =', monitor.isRunningState));
monitor.start();

success Closed
phase closed heuristic false Mar 10, 2026
stopped; running = false

MarketMonitor options: liveIntervalSec, closedIntervalSec, warnIntervalSec, proxies (proxies are called at <proxy>/api/v1/markets/nasdaq/status, i.e. a ts-cloud service). Phases: "open" | "pre-market" | "after-hours" | "closed". It emits status-change after the first successful poll and on each change, falls back to a time-based heuristic during fetch failures (heuristic = true), and emits stopped. Properties: isRunningState, currentPhase.

Against the real Nasdaq API illustrative

const result = await MarketStatus.getStatus();
if (result.status === 'success') {
  console.log(`Nasdaq Status: ${result.value.mrktStatus}`);
  console.log(`Sleeping ${MarketStatus.getSleepDuration(result.value)} ms`);
}

10.2 MarketSymbols (symbol directory)

new MarketSymbols(db?, ingestors?). get(symbol) returns a MarketSymbolRow (symbol, name, type 'rt'|'eod', class, ts, active) or null; refresh() forces a reload; close() releases the store. The backend is the constructor argument (a path means SQLite, mongodb:// or mongodb+srv:// means MongoDB, { dbUrl, dbToken } means Turso) or markets.nasdaq.symbols.store (sqlite default, turso, mongodb). On Node it searches store, then Nasdaq API, then ingestors; on edge runtimes API first.

Load the directory from stub files and look up symbols ran locally

The refresh normally downloads two files from Nasdaq's FTP/HTTPS directory. Here the two URL keys point at a local server serving files in the same format, and minRows (default 1000; a guard against truncated downloads) is lowered for the demo.

cfg.updateValue('markets.nasdaq.symbols.nasdaqListedUrl', `${base}/nasdaqlisted.txt`);
cfg.updateValue('markets.nasdaq.symbols.otherListedUrl',  `${base}/otherlisted.txt`);
cfg.updateValue('markets.nasdaq.symbols.minRows', 2);
const symbols = new MarketSymbols('./symbols-demo.sqlite');
for (const s of ['AAPL', 'IBM', 'QQQ']) console.log(JSON.stringify(await symbols.get(s)));
await symbols.close();

{"symbol":"AAPL","type":"rt","class":"stocks","name":"Apple Inc. - Common Stock","ts":1792108279630,"active":true}
{"symbol":"IBM","type":"rt","class":"stocks","name":"International Business Machines","ts":1792108279630,"active":true}
{"symbol":"QQQ","type":"rt","class":"etf","name":"Invesco QQQ Trust","ts":1792108279630,"active":true}

Other backends illustrative

new MarketSymbols({ dbUrl: 'libsql://your-db.turso.io', dbToken: 'YOUR_TURSO_TOKEN' });   // Turso
new MarketSymbols('mongodb+srv://user:YOUR_PASSWORD@cluster.example.mongodb.net/corelib');  // MongoDB
new MarketSymbols(undefined, ['https://script.google.com/macros/s/YOUR_ID/exec']);       // + custom ingestor

// or select by configuration:
//   export CORELIB_MARKETS_NASDAQ_SYMBOLS_STORE=mongodb
//   export MONGODB_URI="mongodb+srv://user:YOUR_PASSWORD@cluster.example.mongodb.net/corelib"

• MongoDB runs on Node, Lambda and Cloud Run, not on Cloudflare Workers (use Turso there). Switching backend starts empty; there is no migration.
• A circuit breaker (markets.nasdaq.symbols.breaker, default 30 000 ms) applies to MongoDB only.
• A misconfigured store is only logged by get() (SearchDb query failed), which then falls back to the Nasdaq API; refresh() throws. If lookups unexpectedly hit the API, read the logs.

10.3 Nasdaq API wrapper, headers, Fear and Greed, Top 100, historical data

Header spoofing and input validation, offline ran locally

import { CnnFearAndGreed, getNasdaqHeaders } from '@ckirg/corelib-markets';
console.log(JSON.stringify(await CnnFearAndGreed.getFearAndGreed('15-03-2026')));   // rejected before any request
console.log(Object.keys(getNasdaqHeaders('https://api.nasdaq.com/api/quote/AAPL/info')).join(', '));

{"status":"error","reason":{"message":"Invalid date: expected YYYY-MM-DD or \"Historical\""}}
accept, accept-language, origin, referer, sec-ch-ua, sec-ch-ua-mobile, sec-ch-ua-platform, user-agent

Add or override headers with the config key markets.nasdaq.headers (an object); the Chrome version used in the user agent is markets.chromeVersion.

Live data calls illustrative

import { ApiNasdaqUnlimited, CnnFearAndGreed, CnnFearAndGreedFilter, Historical, getSymbolsTop100 }
  from '@ckirg/corelib-markets';

// Nasdaq: status === 'success' checks the API's own rCode too
const quote = await ApiNasdaqUnlimited.endPoint('https://api.nasdaq.com/api/quote/AAPL/info?assetclass=stocks');

// CNN Fear and Greed: current, full history, or one metric on one date (YYYY-MM-DD)
const current = await CnnFearAndGreed.getFearAndGreed();
const history = await CnnFearAndGreed.getFearAndGreed('Historical', 'full');
const vix     = await CnnFearAndGreed.getFearAndGreed('2026-03-15', CnnFearAndGreedFilter.MarketVolatilityVix);
if (current.status === 'success') console.log(current.value.score, current.value.rating);

// Yahoo Finance v3 daily bars; interval is '1d' | '1wk' | '1mo'
const bars = await Historical.getData('AAPL', { period1: '2023-01-01', interval: '1d' });
if (bars.status === 'success') console.log(bars.value.at(-1));   // { symbol, date, open, high, low, close, volume, adjClose }

// Nasdaq 100 constituents, cached in-process and shared between concurrent callers
const top = await getSymbolsTop100();

These were not run (public network). Other exports: ApiNasdaqQuotes, NasdaqPolling, the Markets namespace object, SymbolStore and SymbolStoreUnavailableError types.

10.4 Real-time streaming

AlpacaStreaming, FinnhubStreaming and YahooStreaming are EventEmitters backed by the Rust WebSocket engine. Construct (synchronous, wrap in try/catch), await init(config), await start(), subscribe([...]). Events: pricing, log, connected, disconnected, reconnecting, error; Alpaca and Yahoo also emit market and silence-reconnect.

Alpaca, Finnhub and Yahoo illustrative

import { AlpacaStreaming, FinnhubStreaming, YahooStreaming } from '@ckirg/corelib-markets';

// Alpaca: credentials via init() or APCA_API_KEY_ID / APCA_API_SECRET_KEY
const alpaca = new AlpacaStreaming();
await alpaca.init({ keyId: 'YOUR_KEY', secretKey: 'YOUR_SECRET', silenceSeconds: 60 });
await alpaca.start();
alpaca.subscribe(['AAPL', 'TSLA']);                       // or { trades?, quotes?, bars? }
alpaca.on('pricing', (d) => console.log(`${d.symbol}: $${d.price}`));
alpaca.on('error', (e) => console.error('error', e));

// Finnhub: token via init() or FINNHUB_API_KEY; payload fields are camelCase
const finnhub = new FinnhubStreaming();
await finnhub.init({ token: 'YOUR_FINNHUB_API_KEY' });
await finnhub.start();
await finnhub.subscribe(['MSFT']);
finnhub.on('pricing', (d) => console.log(d.messageType, d.symbol, d.price, d.timestamp));

// Yahoo: no credentials; the ticker field is `id`, not `symbol`
const yahoo = new YahooStreaming();
await yahoo.init({ silenceSeconds: 45 });
await yahoo.start();
yahoo.subscribe(['AAPL', 'BTC-USD']);
yahoo.on('pricing', (d) => console.log(`${d.id}: $${d.price}`));

alpaca.stop(); yahoo.stop(); await finnhub.stop();

11. Edge proxy service (corelib-cloud)

createRouter(logger?, { platform? }) returns a Hono app. Its app.request(path, init, env) method lets you exercise it in-process without a server; on a platform you use the entry bundles (@ckirg/corelib-cloud/aws, /cloudflare, /cloudrun). The package also exports the sub-routers (kyRouter, nasdaqRouter, marketStatusRouter, historicalRouter, sqlRouter), the Cloud namespace and the AppEnv type.

Health and authentication states ran locally

import { createRouter } from '@ckirg/corelib-cloud';
const app = createRouter(undefined, { platform: 'local-demo' });
const show = async (label, p, init, env) => {
  const r = await app.request(p, init, env);
  console.log(label, r.status, await r.text());
};
await show('health', '/health');
await show('no token configured', '/api/v1/markets/nasdaq/status');
const env = { CORELIB_API_TOKEN: 'demo-token' };
await show('missing header', '/api/v1/ky?url=https://example.com', {}, env);
await show('wrong token', '/api/v1/ky?url=https://example.com', { headers: { authorization: 'Bearer nope' } }, env);

health 200 {"status":"ok","timestamp":"2026-10-16T02:06:59.789Z","service":"ts-cloud","platform":"local-demo"}
no token configured 503 {"status":"error","reason":{"message":"Service authentication is not configured"}}
missing header 401 {"status":"error","reason":{"message":"Unauthorized"}}
wrong token 401 {"status":"error","reason":{"message":"Unauthorized"}}

The service is fail-closed: with no CORELIB_API_TOKEN every /api/v1 route except health answers 503. Wrong or missing tokens answer 401 with a WWW-Authenticate header.

Target restrictions (SSRF guard) ran locally

const auth = { authorization: 'Bearer demo-token' };
await show('loopback blocked', '/api/v1/ky?url=http://127.0.0.1:8080/', { headers: auth }, env);
await show('metadata blocked', '/api/v1/ky', { method: 'POST', headers: { ...auth, 'content-type': 'application/json' },
  body: JSON.stringify({ url: 'http://169.254.169.254/latest/meta-data' }) }, env);
await show('non-nasdaq host', '/api/v1/markets/nasdaq', { method: 'POST', headers: { ...auth, 'content-type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com/x' }) }, env);

loopback blocked 400 {"status":"error","reason":{"message":"Target address is not allowed"}}
metadata blocked 400 {"status":"error","reason":{"message":"Target address is not allowed"}}
non-nasdaq host 400 {"status":"error","reason":{"message":"Target host is not on the allow-list"}}

The guard inspects the URL text only; a public hostname that resolves to a private address, and redirects, are not detected. Keep the token secret.

SQL endpoint against a local SQLite file ran locally

The handler reads CORELIB_TURSO_URL and CORELIB_TURSO_TOKEN from the bindings or process.env; a file: URL works locally.

const env = { CORELIB_API_TOKEN: 'demo-token', CORELIB_TURSO_URL: 'file:./cloud-demo.db', CORELIB_TURSO_TOKEN: '' };
const sql = async (body) => {
  const r = await app.request('/api/v1/sql', { method: 'POST',
    headers: { authorization: 'Bearer demo-token', 'content-type': 'application/json' },
    body: JSON.stringify(body) }, env);
  console.log(r.status, await r.text());
};
await sql({ sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, active INTEGER)' });
await sql({ sql: 'INSERT INTO users (name, active) VALUES (?, ?)', params: ['ada', 1] });
await sql({ sql: 'SELECT * FROM users WHERE active = ?', params: [1] });
await sql({ sql: 'SELECT * FROM users', params: 'oops' });
await sql({});

200 {"status":"success","value":{"rows":[],"affectedRows":0,"lastInsertId":"0"}}
200 {"status":"success","value":{"rows":[],"affectedRows":1,"lastInsertId":"1"}}
200 {"status":"success","value":{"rows":[{"id":1,"name":"ada","active":1}],"affectedRows":0}}
400 {"status":"error","reason":{"message":"Invalid params: expected an array or an object"}}
400 {"status":"error","reason":{"message":"Missing SQL query"}}

Calls to a deployed service illustrative

export CORELIB_API_TOKEN=YOUR_TOKEN
curl https://your-service-url/health

# generic proxy, single and bulk
curl -X POST https://your-service-url/api/v1/ky \
  -H "Authorization: Bearer $CORELIB_API_TOKEN" -H "Content-Type: application/json" \
  -d '{ "url": "https://api.github.com/zen" }'
curl -X POST https://your-service-url/api/v1/ky \
  -H "Authorization: Bearer $CORELIB_API_TOKEN" -H "Content-Type: application/json" \
  -d '{ "endPoints": [ { "url": "https://api.a.com/status" }, { "url": "https://api.b.com/data", "options": { "timeout": 2000 } } ] }'

# transparent GET (this is what RequestProxied calls)
curl -H "Authorization: Bearer $CORELIB_API_TOKEN" "https://your-service-url/api/v1/ky?url=https://api.github.com/zen"

# market data
curl -H "Authorization: Bearer $CORELIB_API_TOKEN" https://your-service-url/api/v1/markets/nasdaq/status
curl -H "Authorization: Bearer $CORELIB_API_TOKEN" https://your-service-url/api/v1/markets/nasdaq/groups/top100
curl -X POST https://your-service-url/api/v1/markets/nasdaq/historical \
  -H "Authorization: Bearer $CORELIB_API_TOKEN" -H "Content-Type: application/json" \
  -d '{ "symbol": "AAPL", "options": { "period1": "2023-01-01", "interval": "1d" } }'

Build and deploy illustrative

From a clone, pnpm --filter @ckirg/corelib-cloud build (script build in ts-cloud) produces dist/cloudflare/worker.js, dist/aws/handler.mjs and dist/cloudrun/server.js. Deploying is outside the scope of the local examples and was not run:

# Cloudflare (from ts-cloud/)
pnpm exec wrangler secret put CORELIB_API_TOKEN
pnpm exec wrangler deploy

# AWS Lambda (from the repo root; needs docker, pnpm, zip)
scripts/package-lambda.sh
aws lambda update-function-code --function-name corelib --zip-file fileb://ts-cloud/dist/function.zip

# Cloud Run
gcloud run deploy ts-cloud --source . --command node --args dist/cloudrun/server.js

Environment for deployments: CORELIB_API_TOKEN (required), CORELIB_TURSO_URL and CORELIB_TURSO_TOKEN (SQL route only), PORT (Cloud Run, default 3000). Keep the Worker's [alias] stubs in wrangler.toml; removing them breaks the bundle. On Lambda the native module must be built against glibc 2.34, which is why the script builds inside amazonlinux:2023.

12. Configuration reference

Config keys (bundled defaults)

Environment variables

Command-line flags

-C file / --config file / --config=file load a config file (or URL); every other --a-b-c value / --a-b-c=value / --a-b-c (true) sets key a.b.c. Keys containing __proto__, constructor or prototype segments are dropped.

13. Recipes

A self-contained HTTP test harness ran locally

This is the stub server used by the section 5 examples. It serves a JSON quote, a flaky endpoint (two 503s then 200), an echo endpoint and a 404.

// stub.mjs
import http from 'node:http';
import { endPoint } from '@ckirg/corelib';

let hits = 0;
const srv = http.createServer((req, res) => {
  const u = new URL(req.url, 'http://x');
  res.setHeader('content-type', 'application/json');
  if (u.pathname === '/quote/AAPL') return res.end(JSON.stringify({ symbol: 'AAPL', price: 189.5 }));
  if (u.pathname === '/flaky') {
    if (++hits < 3) { res.statusCode = 503; return res.end('busy'); }
    return res.end('{"ok":true}');
  }
  if (u.pathname === '/echo') {
    let b = ''; req.on('data', (c) => (b += c));
    return req.on('end', () => res.end(JSON.stringify({ method: req.method, body: b,
      ct: req.headers['content-type'], auth: req.headers.authorization })));
  }
  res.statusCode = 404; res.end('{"error":"not found"}');
}).listen(0, async () => {
  const base = `http://127.0.0.1:${srv.address().port}`;
  console.log((await endPoint(`${base}/flaky`, { retry: { limit: 4, backoffLimit: 200 } })).value.body, 'hits', hits);
  srv.close();
});

{ ok: true } hits 3

Production-style start-up: config, logger, then work ran locally

// main.mjs  (run as: NODE_ENV=production LOG_LEVEL=info node main.mjs --retrieve-retry-limit=2)
import { ConfigManager, logger } from '@ckirg/corelib';

const config = ConfigManager.getInstance();
await config.initialize();                      // CLI > env > file > defaults
const log = logger.child({ section: 'main' });
log.info('starting', { retryLimit: config.get('retrieve.retry.limit') });

{"level":30,"time":1792108608111,"pid":3257669,"hostname":"vmi3624072","section":"main","retryLimit":2,"msg":"starting"}

In production mode the logger writes one JSON object per line, which is what log shippers expect; retryLimit is 2 from the CLI flag.

Proxy all traffic through your own ts-cloud deployment illustrative

import { RequestProxied } from '@ckirg/corelib';
const client = new RequestProxied(['https://your-service-url/api/v1/ky']);
// the proxy expects an Authorization header: pass it per call via options
const r = await client.endPoint('https://api.github.com/zen', '', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});

Because RequestProxied builds <proxy>/?url=<target>, the base you pass already includes the route path (/api/v1/ky), and the transparent GET route returns the target's body and status directly.

14. Troubleshooting

15. Where the docs and the code disagree

These were found while verifying the examples. The guide follows the code's behaviour where it could be observed.

1. Install instructions. The ts-core, ts-markets and ts-cloud READMEs say "Not on the public npm registry" (ts-core and ts-markets show a v0.1.17 GitHub tarball install); the root README says they are on the public npm registry (version 0.4.0 in all manifests). npm view @ckirg/corelib version returns 0.4.0, so the root README is right and the package READMEs are out of date.
2. Tool versions. The root README shows a TypeScript 5.0+ badge while the catalog pins TypeScript ^6.0.3.
3. RequestProxied pruning. The ts-core README says unhealthy proxies are pruned "on first failure"; the code (and its doc comment) removes a proxy after 3 consecutive failures.
4. Database config type. The ts-core README example createDatabase({ dialect: 'sqlite', url }) omits mode, which BaseDbConfig declares as required ('stateless' | 'stateful'). It runs at runtime without it, but TypeScript users get a type error.
5. RequestUnlimited. READMEs describe a RequestUnlimited class; the package exports the functions endPoint and endPoints (plus RequestProxied), not a class of that name.
6. Native addon version. Core.getVersion() returned 0.2.0 from the bundled ts-core/corelib-rust.node while the package is 0.4.0.
7. Error bodies. Failed HTTP results carry body: "[Body already consumed]", so the server's error payload is not retrievable from reason.body.
8. Streaming clients keep the process alive (0.4.0). AlpacaStreaming.init({}) with no credentials resolves in milliseconds, but in 0.4.0 a process that merely constructs an AlpacaStreaming, FinnhubStreaming or YahooStreaming never exits naturally, even after init() and stop(). The cause was strong native callbacks holding Node's event loop open. It is fixed on main after 0.4.0 (callbacks are weak; a running feed holds a keep-alive timer until stop()), so on 0.4.0 end such scripts with process.exit().

16. Appendix: quick reference

@ckirg/corelib

@ckirg/corelib-markets

MarketStatus.getStatus/getSleepDuration, MarketMonitor, MarketSymbols (get, refresh, close), ApiNasdaqUnlimited.endPoint, ApiNasdaqQuotes, getNasdaqHeaders, CnnFearAndGreed.getFearAndGreed with CnnFearAndGreedFilter, Historical.getData, NasdaqPolling, getSymbolsTop100, AlpacaStreaming, FinnhubStreaming, YahooStreaming, namespace Markets.

@ckirg/corelib-cloud

createRouter(logger?, { platform? }), Cloud, kyRouter, nasdaqRouter, marketStatusRouter, historicalRouter, sqlRouter, type AppEnv; subpath bundles /aws, /cloudflare, /cloudrun.

Monorepo scripts (from a clone)