@skystate/core

@skystate/core is the framework-agnostic SkyState client library. It handles HTTP fetching, caching, pub/sub notification, and auto-registration of missing config keys.

---

Installation

npm install @skystate/core

---

Public API

Classes

Export	Description
ConfigStore	The main client class. Fetches config, caches it, and notifies subscribers when values change.
AutoRegistrar	Batches and debounces missing-key registrations in development mode. Used internally by ConfigStore.
HttpClient	Handles HTTP fetch with Cache-Control scheduling and tab visibility re-fetching. Used internally by ConfigStore.
ConfigCache	In-memory cache with structural sharing for stable object references. Used internally by ConfigStore.
PubSubEmitter	Path-keyed subscription registry. Used internally by ConfigStore.
SkyStateError	Typed error class with a code string and optional HTTP status.

Functions

Export	Description
getOrCreateStore(options)	Get or create a singleton ConfigStore for the given (apiUrl, accountSlug, projectSlug, environment) tuple.

Constants

Export	Description
VALID_ENVIRONMENTS	['development', 'staging', 'production'] — the allowed values for environment slugs.

Types

Export	Description
Environment	'development' | 'staging' | 'production'
ConfigStoreOptions	Options passed to getOrCreateStore.
ConfigEnvelope	The shape of a config response from the API: { version, lastModified, config }.
Version	Semantic version object: { major, minor, patch }.
SkyStateConfig	Basic config identity: { apiUrl, accountSlug, projectSlug, environmentSlug }.
HttpClientOptions	Options for the HttpClient constructor.
OnUpdateCallback	(envelope: ConfigEnvelope) => void
OnErrorCallback	(error: Error) => void

---

Sections

• ConfigStore — initialization, reading values, and subscribing to changes
• Environments — how build-time environment variables map to server environment slugs
• Auto-registration — automatic key creation in development mode

---

Error Handling

All SDK errors are thrown as SkyStateError instances:

import { SkyStateError } from '@skystate/core';

try {
  const store = getOrCreateStore({ /* ... */ });
} catch (err) {
  if (err instanceof SkyStateError) {
    console.error(err.code);    // e.g. 'invalid_environment'
    console.error(err.message); // human-readable description
    console.error(err.status);  // HTTP status if applicable, otherwise undefined
  }
}

Error Codes

Code	When thrown
environment_resolution_failed	resolveEnvironment() threw an exception
invalid_environment	resolveEnvironment() returned a value not in VALID_ENVIRONMENTS
fetch_failed	The HTTP GET for config returned a non-2xx status
patch_failed	The HTTP PATCH for auto-registration returned a non-2xx, non-409 status