You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
121 lines
4.3 KiB
121 lines
4.3 KiB
# Active
|
|
|
|
Active is a Svelte/SvelteKit application runtime: a coherent set of small engines for app composition, language resolution, diagnostics, formats, DOM/frontend state, storage, HTTP, timers, cache, sessions, authentication and permissions.
|
|
|
|
The goal is not to replace Svelte. Active fills the layer most teams rebuild differently in every app: the runtime contract between UI, server flows, security, persistence and observability.
|
|
|
|
## Status
|
|
|
|
Active is pre-`0.1.0`.
|
|
|
|
- The current line is suitable for framework exploration, internal apps and integration testing.
|
|
- The `0.1.x` goal is a stable public surface for the always-present roots.
|
|
- MFA, a full OAuth provider catalog, production WebAuthn and npm publication are intentionally outside the first stable cut.
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Open:
|
|
|
|
- `http://localhost:5173/active` for the ecosystem documentation.
|
|
- `http://localhost:5173/test/ecosystem` for the full integration test page.
|
|
- `http://localhost:5173/test/auth` for the authentication harness.
|
|
|
|
## Runtime Shape
|
|
|
|
Active separates logic into three layers:
|
|
|
|
- `src/libs/*`: pure contracts, constants, helpers and shared types.
|
|
- `src/svrs/*`: server-authoritative engines and adapters.
|
|
- `src/arts/*`: Svelte-facing active engines and client/runtime integrations.
|
|
|
|
Root modules follow the same vocabulary:
|
|
|
|
- `createEngineX(...)` creates an imperative, framework-neutral engine.
|
|
- `createActiveX(...)` creates a Svelte 5 reactive wrapper.
|
|
- `createActiveApp(...)` composes the always-present roots into one app runtime.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
import { createActiveApp } from '$aapp';
|
|
import { consoleTransport, createEngineLogger } from '$logr';
|
|
|
|
const Logger = createEngineLogger({
|
|
transports: [consoleTransport()]
|
|
});
|
|
|
|
const App = createActiveApp({
|
|
logger: Logger,
|
|
lang: { schema, defaultLocale: 'es' },
|
|
frontend: { theme: 'base' }
|
|
});
|
|
|
|
App.Lang.t('common.ok');
|
|
App.Formats.currency.format(99.5);
|
|
App.setLocale('es-MX');
|
|
```
|
|
|
|
## Modules
|
|
|
|
- `aapp`: composition root and shared locale source.
|
|
- `lang`: typed translations, fallback resolution and literal fallback syntax.
|
|
- `logr`: logger engine, transports and module diagnostics sink.
|
|
- `fmts`: numbers, currency, units and dates derived from locale unless explicitly locked.
|
|
- `fend`: application frontend state such as theme, direction, density and scroll/focus behavior.
|
|
- `adom`: DOM utilities used by frontend and UI layers.
|
|
- `stor`: typed sync storage entries with adapters, validation, versioning and TTL.
|
|
- `http`: typed HTTP client/server contracts and shared HTTP constants.
|
|
- `timr`: deterministic timer scheduler, clocks and backoff.
|
|
- `cach`: data cache with policies, tags, stale handling and adapters.
|
|
- `sess`: session lifecycle.
|
|
- `auth`: server-first authentication flows plus a safe active client reflector.
|
|
- `perm`: authorization engine and active permission client.
|
|
- `conn`: realtime connections and channels.
|
|
- `sium`: validation schema helpers.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
npm run check
|
|
npm test
|
|
npm run build
|
|
npm run test:static
|
|
npm run test:bundle
|
|
npm run test:all
|
|
```
|
|
|
|
`npm run lint` exists, but the full-repo lint pass is still a pre-`0.1` cleanup item.
|
|
Use it for focused work and do not add new lint debt.
|
|
|
|
Rules that matter for contributions:
|
|
|
|
- Do not put public strings, event names, logger categories or route names inline in implementation files. Define constants first.
|
|
- Engines must not depend on Svelte runes or browser globals.
|
|
- Active modules must expose the common active-engine shape where applicable.
|
|
- Security-sensitive behavior needs tests before it is considered closed.
|
|
- Documentation and code comments are written in English.
|
|
|
|
## Release Readiness
|
|
|
|
The active checklist before `0.1.0` lives in `docs/before_0_1.md`. The short version:
|
|
|
|
- security gaps in `auth`, `perm` and `cach` closed or explicitly out of surface;
|
|
- root API surface snapshot-tested;
|
|
- documentation good enough to onboard without reading source;
|
|
- bundle smoke keeps `createActiveApp({})` under the current `0.1` budget;
|
|
- CI runs typecheck, tests, build, static smoke and bundle smoke; full-repo lint cleanup is tracked separately before `0.1.0`;
|
|
- security policy and changelog exist.
|
|
|
|
## Security
|
|
|
|
Please read `SECURITY.md` before reporting or fixing authentication, session, permission, cache or storage issues.
|
|
|
|
## Brand
|
|
|
|
The visual direction and asset checklist live in `BRAND.md`.
|