npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@idlekit/core

v0.8.0

Published

Bun-first scenario compilation, simulation, analysis, and reporting for idle game economies.

Readme

@idlekit/core

Simulation and analysis primitives for idle game economy design. It compiles scenarios, executes runs, and evaluates long-horizon KPIs and design-facing metrics. Official support in v1: Bun >=1.4.2 only. Node.js and browser runtimes are not part of the v1 compatibility contract.

bun add @idlekit/core

Requires Bun >=1.4.2.

Use this package when you need:

  • scenario validation / compilation
  • simulation loop and stepOnce
  • built-in strategies and tuning primitives
  • growth, milestone, session-pattern, and Monte Carlo analysis
  • hypothetical LTV estimates via deriveMonetizationConfig, estimateLtvPerUser and estimateLtvDistribution

LTV estimates

Import the three LTV functions, the retentionAtDay / progressionFactor helpers and the MonetizationConfig, LtvEstimateArgs, LtvDistributionArgs, LtvPointEstimate and LtvDistribution types from @idlekit/core. Pass a ScenarioV1 to deriveMonetizationConfig; pass the returned config, horizonDays and progression to estimateLtvPerUser. estimateLtvDistribution also reads draws, quantiles and seed; an omitted one falls back to config.uncertainty, and an explicit one wins. It always samples: config.uncertainty.enabled is the caller's switch for whether to call it, as in the CLI. The CLI uses the same implementation.

LTV is undiscounted cumulative value. A horizon of H days covers install days [0, H): day 0 is the install day, active by definition, as in telemetry and idk calibrate. A fractional last day is prorated at that day's retention, so 0.5 days is half of the install day. Earlier releases covered days [1, H], dropped install-day revenue and charged a 0.5-day horizon at D1 retention. The same horizon now adds the install day and drops day H, so LTV values change and usually rise.

Inputs are hypothetical assumptions, in one caller-chosen currency per installed user. Defaults are not observed retention or measured revenue. Net revenue applies platform fees and gross margin; LTV then subtracts CPI, including at a zero-day horizon. Finite progression is clamped to 0..1. Quantile bands describe sensitivity to assumptions, not fitted confidence intervals or evidence of enjoyment/retention.

Synchronous limits: 0..36500 days, 1..100000 draws and at most 10000000 draw-days (at least one work unit per draw). Quantiles must be 1..101 distinct values in 0..1. Each output key is the exact percent (q50, q90, q2.5 for 0.025, q12.4 for 0.124), so keys never collide or round. The seed must be an integer in 0..4294967295; other seeds throw instead of being folded. retentionAtDay requires a finite day >= 0 and a valid curve (day 0 is 1, any day in (0, 1] reads D1, and anchors from D1 on are linear); progressionFactor rejects NaN logs and a span that is not finite and positive, and treats an infinite worth log (zero worth) as no progression. Invalid inputs and numeric overflow throw RangeError. Sampling shrinks inconsistent correlation matrices toward independence. Complete-cohort retention observation and safe patch application are available in core; the public idk calibrate CLI shares the observation and planning implementation. Public estimate configs accept quantile endpoints too. The point estimate validates the whole config, including the uncertainty defaults the distribution reads; key distinctness and the seed range are checked when the distribution uses them. ScenarioV1 authored quantiles retain their existing (0, 1) schema when passed to deriveMonetizationConfig.

Partial scenario retention overrides keep the CLI's independent defaults. For example, d1: 0.1 alone retains the default d7: 0.2; estimates preserve that existing interpolation. Explicit complete scenario curves still follow scenario ordering validation. Direct estimate configs validate each rate's range without adding an ordering constraint to completed defaults. The point projection and the distribution interpolate such a rising curve the same way: one shared retention shock scales every anchor, and sampling no longer clips a later anchor to the preceding one, so a zero-uncertainty distribution equals the point projection.

Observed cohort retention

Import observeCohort, compareRetention, planRetentionPatch and applyRetentionPatch from @idlekit/core. CohortActivityRow requires userId and integer day; active defaults to true. Money fields are optional and are never fitted by these retention APIs. Every installed user needs a day-zero row, including nonreturners, and the caller must provide a complete activity export with a common, fully mature observedThroughDay. The API checks consistency; it cannot prove export completeness.

observeCohort(rows, cutoff) preserves future rates/intervals as null. planRetentionPatch returns ready, unavailable or requires-review; every unobserved target day requires an explicit retained assumption. Observations that rise or conflict with retained values remain unchanged and cannot become an automatic patch. applyRetentionPatch({ scenario, observation }) recomputes the plan, validates and returns an independent scenario copy. It throws if the patch is not ready and never replaces revenue, fees, CPI, uncertainty, cohort size or unobserved retention. assertCohortObservation validates serialized input.

See the complete SDK example and the cohort export guide.

Game-specific offline settlement

simulateSessionPattern({ scenario, pattern, prepareOffline }) optionally calls a synchronous SessionOfflinePreparer once per nonempty absence. It receives ctx, model, a state snapshot, seconds, wallStartT, wallEndT and the current policy snapshot. Numeric prototypes are preserved in the snapshots; treat the shared engine, context and model as immutable. Use the explicit wall timestamps for expiry checks after earlier capped gaps.

Return any of model, stepSec and policy. They apply only to this gap; omission inherits the scenario setting. policy replaces cap/decay, so {} removes both. The session's action policy stays in scenario.run.offline.actions; a callback cannot override it. A replacement model declares its own clocks.respondsTo needs. The SDK still performs reward ticks, goals, until checks, action filtering, observations and wall/reward accounting.

A game with one atomic settlement can compute it on the snapshot and return a model that imports its result in one reward tick, with stepSec equal to its effective credited seconds (use a positive step when credit is zero). Stops are checked at tick boundaries; a one-tick settlement does not expose intermediate game states. Preparation itself must not grant an external reward: zero credit or an already-reached goal may execute no transition at all. For partial settlement or intra-gap goals, supply a model that evolves per smaller tick.

This is an SDK callback, not a JSON scenario field. The default session path is unchanged. See the big-number offline example.

Quick example

import {
  analyzeGrowth,
  compileScenario,
  createModelRegistry,
  createNumberEngine,
  defineModelFactory,
  runScenario,
  validateScenarioV1,
} from "@idlekit/core";

type Vars = { owned: number };

const linearFactory = defineModelFactory<number, "COIN", Vars>({
  id: "linear",
  version: 1,
  create() {
    return {
      id: "linear",
      version: 1,
      income(ctx, state) {
        return {
          unit: ctx.unit,
          amount: ctx.E.add(1, Number(state.vars.owned ?? 0)),
        };
      },
      actions() {
        return [];
      },
    };
  },
});

const registry = createModelRegistry([linearFactory]);

const scenario = {
  schemaVersion: 1,
  unit: { code: "COIN" },
  policy: { mode: "drop" },
  model: { id: "linear", version: 1 },
  initial: {
    wallet: { unit: "COIN", amount: "0" },
    vars: { owned: 0 },
  },
  clock: { stepSec: 1, durationSec: 60 },
};

const validated = validateScenarioV1(scenario, registry);
if (!validated.ok || !validated.scenario) {
  throw new Error(`scenario should validate: ${JSON.stringify(validated.issues)}`);
}

const E = createNumberEngine();
const compiled = compileScenario({
  E,
  scenario: validated.scenario,
  registry,
});
const run = runScenario(compiled);
const growth = analyzeGrowth({ run, series: "money", windowSec: 10 });

console.log(
  JSON.stringify({
    endMoney: E.toString(run.end.wallet.money.amount),
    growthSegments: growth.segments,
  }),
);

Money primitives

Engines, Money/MoneyState, tickMoney, notation, and money serde are implemented in @idlekit/money. @idlekit/core re-exports them for compatibility, so the example above can import createNumberEngine from core. These re-exports stay in v1 but are scheduled for deprecation; prefer @idlekit/money in new code that only needs money primitives. breakEternityEngine is a placeholder that throws on every call and is not implemented in v1.

Runtime

For the duration of an in-memory runScenario or applyOfflineSeconds result, import runElapsedSec from @idlekit/core and read runElapsedSec(run). It uses run.stop.elapsedSec, the sum of tick seconds. state.t is the absolute reward timestamp; at a large starting timestamp, run.end.t - run.start.t can round differently. For example, ten 0.1-second ticks starting at 1e15 simulate about one second while the timestamps differ by 1.25 seconds. Results without a stop record fall back to that timestamp difference. A step-budget stop can shorten an individual run before the requested duration; check run.stop?.reason or use assertHorizonReached(run, label) when the full horizon is required.

For simulateSessionPattern, read summary.elapsedSec for wall time, summary.activeSec for active tick seconds, and summary.offlineCreditedSec for offline reward tick seconds. The aggregate session.run has no per-run stop record, so runElapsedSec(session.run) uses the timestamp fallback. summary.rewardSec is also a reward timestamp difference; use the active and offline credited totals when you need simulated tick seconds.

@idlekit/core is maintained as a Bun-first ESM package.

Documentation