@lithia-js/core 1.0.0-canary.2 → 1.0.0-canary.21

package/README.md

@@ -2,59 +2,42 @@
   <a href="https://github.com/lithia-framework/lithia">
     <img alt="Lithia logo" src="https://raw.githubusercontent.com/lithia-framework/lithia/canary/.github/assets/logo.svg" height="128">
   </a>
-  <h1>Lithia</h1>
-  <p><strong>The Node.js framework that makes API development feel like magic</strong></p>
+  <h1>@lithia-js/core</h1>
+  <p><strong>The main Lithia runtime package.</strong></p>
 
-<a href="https://www.npmjs.com/package/lithia"><img alt="NPM version" src="https://img.shields.io/npm/v/lithia.svg?style=for-the-badge&labelColor=000000"></a>
-<a href="https://github.com/lithia-framework/lithia/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/lithia.svg?style=for-the-badge&labelColor=000000"></a>
+  <p>Routes, events, async tasks, startup bootstrap, config, and the public runtime APIs.</p>
+
+<a href="https://www.npmjs.com/package/@lithia-js/core"><img alt="NPM version" src="https://img.shields.io/npm/v/@lithia-js/core.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://github.com/lithia-framework/lithia/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@lithia-js/core.svg?style=for-the-badge&labelColor=000000"></a>
 <a href="https://opencollective.com/lithiajs"><img alt="Support Lithia" src="https://img.shields.io/badge/Support%20Lithia-blueviolet.svg?style=for-the-badge&logo=OpenCollective&labelColor=000000&logoWidth=20"></a>
 
 </div>
 
-## Getting Started
-
-Lithia is a next-generation Node.js framework that enables you to build powerful APIs with file-based routing, built-in WebSocket support, and a beautiful development interface.
-
-- Visit our [Learn Lithia](https://lithiajs.com/docs) guide to get started.
-- Check out the [Examples](https://github.com/lithia-framework/lithia/tree/main/examples) to see Lithia in action.
-
-## Documentation
-
-Visit [https://lithiajs.com/docs](https://lithiajs.com/docs) to view the full documentation.
-
-## Community
+## Overview
 
-The Lithia community can be found on [GitHub Discussions](https://github.com/lithia-framework/lithia/discussions) where you can ask questions, voice ideas, and share your projects with other people.
+`@lithia-js/core` provides the main framework primitives:
 
-## Contributing
+- `defineConfig()` for `lithia.config.ts`
+- file-based HTTP routes and Socket.IO events
+- request/response primitives and route/event hooks
+- dependency injection with `provide()` and `useDependency()`
+- native async tasks with `executeTask()` and `dispatchTask()`
+- optional `src/app/server.ts` startup bootstrap
+- route metadata types for OpenAPI generation
 
-Contributions to Lithia are welcome and highly appreciated. However, before you jump right into it, we would like you to review our [Contribution Guidelines](CONTRIBUTING.md) to make sure you have a smooth experience contributing to Lithia.
+## Example
 
----
+```ts
+import type { RouteHandler } from "@lithia-js/core";
 
-## Support the Project
+const hello: RouteHandler = async (_req, res) => {
+	res.json({ message: "Hello, world!" });
+};
 
-If Lithia makes your life easier, consider supporting it:
+export default hello;
+```
 
-- **Star** this repository
-- **Share** on social media
-- **Sponsor** via [OpenCollective](https://opencollective.com/lithiajs)
-- **Report bugs** and suggest improvements
+## Internal layout
 
----
-
-## License
-
-Lithia is [MIT licensed](LICENSE). Free for personal and commercial use.
-
----
-
-<div align="center">
-  <p><strong>Built with ❤️ by the Lithia community</strong></p>
-  <p>
-    <a href="https://github.com/lithia-framework/lithia">GitHub</a> •
-    <a href="https://lithiajs.com">Documentation</a> •
-    <a href="https://opencollective.com/lithiajs">OpenCollective</a> •
-    <a href="https://github.com/lithia-framework/lithia/discussions">Discussions</a>
-  </p>
-</div>
+The internal package layout is documented in
+[src/README.md](./src/README.md).

package/dist/_index.d.ts

@@ -0,0 +1,245 @@
+import { L as LithiaError, a as LithiaOptions, R as Route, E as Event } from './protocol-DBwVPJYN.js';
+export { C as CFG_GLOBAL_KEY, b as RouteNotFoundError } from './protocol-DBwVPJYN.js';
+import { T as TaskCore } from './tasks-X-3clDS8.js';
+import '@lithia-js/utils';
+import 'c12';
+
+type Environment = "test" | "build" | "production" | "development";
+
+/**
+ * Thrown when a Lithia hook is used outside a managed Lithia execution
+ * context.
+ */
+declare class NotInLithiaContextError extends LithiaError {
+    constructor();
+}
+
+/**
+ * Minimal runtime options required to bootstrap the Lithia host.
+ */
+interface LithiaOpts {
+    /**
+     * Runtime environment mode used to load config, manifests, and workers.
+     */
+    environment: Environment;
+}
+/**
+ * Main-process orchestrator for the Lithia runtime.
+ *
+ * The host is responsible for loading configuration and manifests, building the
+ * app, spawning the app worker, and coordinating async task execution.
+ */
+declare class HostSupervisor {
+    private readonly opts;
+    private _config;
+    private _env;
+    private readonly _builder;
+    private readonly _manifestStore;
+    private readonly _appSupervisor;
+    private readonly _taskRunner;
+    private _appCount;
+    private _lastPortUsed;
+    /**
+     * Creates the main-process supervisor for a Lithia runtime instance.
+     *
+     * The supervisor owns configuration loading, environment snapshots, build
+     * orchestration, manifest loading, app worker lifecycle, and async task
+     * execution coordination.
+     *
+     * @param {LithiaOpts} opts - Minimal host runtime options.
+     * @throws {Error} Throws when instantiated outside the Node.js main thread.
+     */
+    constructor(opts: LithiaOpts);
+    /**
+     * Returns the resolved runtime configuration for the current host lifecycle.
+     *
+     * In production, the config is read from the global host runtime slot
+     * exposed through `CFG_GLOBAL_KEY`. In other environments, the in-memory
+     * loaded config snapshot is returned.
+     */
+    get config(): LithiaOptions;
+    /**
+     * Returns the environment mode assigned to this host instance.
+     */
+    get environment(): Environment;
+    /**
+     * Returns whether the supervised app worker has reported readiness.
+     */
+    get isAppReady(): boolean;
+    /**
+     * Returns the currently loaded route manifest entries.
+     */
+    get routes(): Route[];
+    /**
+     * Returns the currently loaded event manifest entries.
+     */
+    get events(): Event[];
+    /**
+     * Returns the currently loaded async task manifest entries.
+     */
+    get tasks(): TaskCore[];
+    /**
+     * Loads the user configuration file into the host runtime.
+     *
+     * This is skipped in production, where config is expected to be available
+     * through the global runtime slot.
+     *
+     * @returns {Promise<void>} Resolves after the config snapshot has been
+     * loaded when applicable.
+     */
+    loadConfig(): Promise<void>;
+    /**
+     * Loads and merges configured environment files into the host snapshot.
+     *
+     * Files are loaded in config order, and later files override earlier keys.
+     * Only files that currently exist are considered.
+     *
+     * @returns {Promise<Record<string, string>>} Copy of the merged environment
+     * snapshot.
+     * @throws {LithiaError} Throws when configuration has not been loaded yet.
+     */
+    loadEnv(): Promise<Record<string, string>>;
+    /**
+     * Loads the routes manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the route manifest cache has been
+     * refreshed.
+     */
+    loadRoutes(): Promise<void>;
+    /**
+     * Loads the events manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the event manifest cache has been
+     * refreshed.
+     */
+    loadEvents(): Promise<void>;
+    /**
+     * Loads the async tasks manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the task manifest cache has been
+     * refreshed.
+     */
+    loadTasks(): Promise<void>;
+    /**
+     * Returns a copy of the currently loaded environment snapshot.
+     *
+     * @returns {Record<string, string>} Shallow copy of the host environment
+     * snapshot.
+     */
+    getEnvSnapshot(): Record<string, string>;
+    /**
+     * Replaces the in-memory resolved config snapshot.
+     *
+     * @param {LithiaOptions} config - Config snapshot that should replace the
+     * current in-memory value.
+     */
+    replaceConfig(config: LithiaOptions): void;
+    /**
+     * Replaces the in-memory environment snapshot.
+     *
+     * @param {Record<string, string>} env - Environment snapshot that should
+     * replace the current in-memory value.
+     */
+    replaceEnv(env: Record<string, string>): void;
+    /**
+     * Builds the application output and manifests.
+     *
+     * Returns `true` when the build succeeds. In non-build environments, failures
+     * are reported and surfaced as `false` so the caller can decide how to
+     * recover.
+     *
+     * @returns {Promise<boolean>} `true` when the build succeeds, otherwise
+     * `false` outside build mode.
+     * @throws {unknown} Rethrows build failures when the host runs in `build`
+     * mode.
+     */
+    build(): Promise<boolean>;
+    /**
+     * Loads config/env and prints the CLI header for the current run.
+     *
+     * @returns {Promise<void>} Resolves after config, env, and header output are
+     * ready.
+     */
+    setup(): Promise<void>;
+    /**
+     * Starts the app worker using the latest manifests and runtime state.
+     *
+     * @returns {Promise<void>} Resolves after manifests are loaded and the app
+     * worker reports readiness.
+     * @throws {Error} Throws when worker startup fails.
+     */
+    start(): Promise<void>;
+    /**
+     * Reloads manifests, resets task workers, and swaps the app worker.
+     *
+     * @returns {Promise<void>} Resolves after manifests are refreshed, task
+     * workers are reset, and the replacement app worker becomes ready.
+     */
+    reload(): Promise<void>;
+    /**
+     * Stops task execution and tears down the app worker.
+     *
+     * @returns {Promise<void>} Resolves after warm task workers and the app
+     * worker have been terminated.
+     */
+    stop(): Promise<void>;
+    /**
+     * Replaces the current app worker with a fresh instance.
+     *
+     * @returns {Promise<void>} Resolves after the replacement app worker reports
+     * readiness.
+     */
+    swapApp(): Promise<void>;
+    /**
+     * Prints the Lithia CLI header and the env files currently in use.
+     *
+     * @returns {Promise<void>} Resolves after header output has been printed.
+     */
+    printHeader(): Promise<void>;
+    /**
+     * Prints the loaded routes in a CLI-friendly tree format.
+     */
+    printRouteTree(): void;
+    /**
+     * Prints the loaded events in a CLI-friendly tree format.
+     */
+    printEventTree(): void;
+    /**
+     * Prints the loaded async tasks in a CLI-friendly tree format.
+     */
+    printTaskTree(): void;
+    /**
+     * Forwards task invocation messages emitted by the app worker to the async
+     * task runner.
+     *
+     * @param {AppToHostEvent} event - Message emitted by the app worker.
+     * @returns {Promise<void>} Resolves after invocation messages are handled or
+     * ignored.
+     */
+    private handleAppMessage;
+    /**
+     * Prints a simple labeled tree for CLI inspection of loaded runtime state.
+     *
+     * @param {string} label - Section label printed above the tree.
+     * @param {T[]} items - Items to render.
+     * @param {(item: T) => string} nameFn - Formatter used for the item label.
+     * @param {(item: T) => string} symbolFn - Formatter used for the item
+     * prefix symbol.
+     */
+    private printTree;
+    /**
+     * Returns the configured env files that currently exist on disk.
+     *
+     * @returns {Promise<string[]>} Existing env files in configured load order.
+     */
+    private getAvailableEnvFiles;
+    /**
+     * Verifies that a config snapshot is available before host operations that
+     * depend on it.
+     *
+     * @throws {LithiaError} Throws when configuration has not been loaded.
+     */
+    private ensureConfigLoaded;
+}
+
+export { HostSupervisor, NotInLithiaContextError };