application-core

A standalone React Native framework core providing EventBus, ServiceLocator, Router/Navigator, Coordinator, mixins, services and shared contexts. Designed to be embedded into any mobile application as a foundation for navigation, theming, dependency injection and scene/layer orchestration.

Requirements

• Node.js 18+
• npm 9+ (or yarn 1.x / pnpm 8+)

Install

npm install

Test commands

All commands are run from the project root.

| Command | Description | |---|---| | npm test | Run the full Jest suite (silent mode — pass/fail only). | | npm run test:verbose | Run Jest with --verbose (shows each it block). | | npm run test:ci | Run Jest in CI mode (--ci --runInBand, no watch). Use for pipelines. | | npm run test:coverage | Run Jest with code coverage. Output: terminal table + coverage/lcov-report/index.html (HTML) and coverage/lcov.info (LCOV). |

Targeted runs

Useful for working on a single area:

# Only the bus module
npm run test:verbose src/bus

# Only one test file
npm run test:verbose src/store/builder.test.ts

# Only tests whose name matches a pattern
npx jest -t "ServiceLocator"

# Watch mode (reruns on change)
npx jest --watch

# Watch with coverage
npx jest --watch --coverage

Coverage thresholds

The project does not enforce a coverage threshold by default — npm run test:coverage is informational. Use the coverage/lcov-report/index.html report to inspect gaps.

Lint

npm run lint

Runs ESLint with --fix across index.* and src/. Configuration is inherited from the ESLint config declared in package.json.

Project layout

src/
  application/    # Application class, init(), module contract, URI utils
  bus/            # EventBus, Event, events registry
  components/     # withLayer / withLocale / withScene / withRefreshProvider / Consumer HOCs
  constants.ts    # Opacity scale
  contexts/       # React contexts (Refresh, Locale, ColorScheme)
  coordinator/    # Coordinator + scene/layer models + React UI
  decorators/     # Singleton
  hooks/          # useColorScheme / useLayer / useLocale / useRefresh / useScene
  locator/        # ServiceLocator
  mixins/         # StateMachineMixin
  navigator/      # Navigator + navigation events
  portal/         # Portal
  router/         # Router + router events
  services/       # Theme, Notification
  store/          # StoreBuilder + LoaderStore
  types.ts        # Immutable<T> utility type
  __fixtures__/   # Reusable test fixtures (makeTestModule)
  __mocks__/      # Jest module mocks (coordinator stub)

plans/            # Test coverage plan and design notes
rules/            # Coding conventions (e.g. unit-test-rules.md)
coverage/         # Output of `npm run test:coverage`

Testing conventions

See rules/unit-test-rules.md for the project's unit-test rules:

• Top-level describe matches the class name (without file suffix).
• Second-level describe uses #methodName for instance methods and .methodName for static methods.
• Third-level describe describes a scenario / context.
• it blocks follow the AAA (Arrange / Act / Assert) paradigm, with each phase visually separated.
• One class per test file. Static and instance variants of the same method get separate describe blocks.

See plans/test-coverage-plan.md for the phased test-coverage roadmap and current status.

Versioning

npm version <major|minor|patch> is wired to postversion which pushes the tag and the commit. Do not publish without running npm test first — the prepublishOnly hook enforces this.

License

UNLICENSED — proprietary, see LICENSE (if present).