@gravito/core 1.0.0-beta.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Carl Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @gravito/core
+
+> The Micro-kernel for Galaxy Architecture. Lightweight, extensible, and built on Photon & Bun.
+
+[![npm version](https://img.shields.io/npm/v/@gravito/core.svg)](https://www.npmjs.com/package/@gravito/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+
+**@gravito/core** is the foundation for building modular backend applications using the **Galaxy Architecture**. It provides a robust Hook system (Filters & Actions) and an Orbit mounting mechanism, allowing you to build loosely coupled, highly extensible systems.
+
+## ✨ Features
+
+- 🪐 **PlanetCore** - A centralized Photon-based kernel to manage your application lifecycle.
+- 📦 **IoC Container** - A lightweight dependency injection container with binding and singleton support.
+- 🧩 **Service Providers** - Modular service registration and booting lifecycle.
+- 🪝 **Hook System** - WordPress-style async **Filters** and **Actions** for powerful extensibility.
+- 🛰️ **Orbit Mounting** - Easily mount external Photon applications (Orbits) to specific paths.
+- 📝 **Logger System** - PSR-3 style logger interface with default standard output implementation.
+- ⚙️ **Config Manager** - Unified configuration management supporting environment variables (`Bun.env`) and runtime injection.
+- 🛡️ **Error Handling** - Built-in standardized JSON error responses and 404 handling.
+- 🚀 **Modern** - Built for **Bun** runtime with native TypeScript support.
+- 🪶 **Lightweight** - Zero external dependencies (except `@gravito/photon`).
+
+## 📦 Installation
+
+```bash
+bun add @gravito/core
+```
+
+## 🚀 Quick Start
+
+### 1. Initialize the Core
+
+```typescript
+import { PlanetCore } from '@gravito/core';
+
+// Initialize with options (v0.2.0+)
+const core = new PlanetCore({
+  config: {
+    PORT: 4000,
+    DEBUG: true
+  }
+});
+```
+
+### 2. Dependency Injection
+
+Use the IoC Container to manage your application services:
+
+```typescript
+import { ServiceProvider, Container } from '@gravito/core';
+
+class CacheServiceProvider extends ServiceProvider {
+  register(container: Container) {
+    // Bind a singleton service
+    container.singleton('cache', (c) => {
+      return new RedisCache(process.env.REDIS_URL);
+    });
+  }
+
+  async boot(core: PlanetCore) {
+    // Perform boot logic
+    core.logger.info('Cache provider booted');
+  }
+}
+
+// Register the provider
+core.register(new CacheServiceProvider());
+
+// Bootstrap the application (runs register() and boot())
+await core.bootstrap();
+
+// Resolve services
+const cache = core.container.make('cache');
+```
+
+### 3. Register Hooks
+
+Use **Filters** to modify data:
+
+```typescript
+core.hooks.addFilter('modify_content', async (content: string) => {
+  return content.toUpperCase();
+});
+
+const result = await core.hooks.applyFilters('modify_content', 'hello galaxy');
+// result: "HELLO GALAXY"
+```
+
+Use **Actions** to trigger side-effects:
+
+```typescript
+core.hooks.addAction('user_registered', async (userId: string) => {
+  core.logger.info(`Sending welcome email to ${userId}`);
+});
+
+await core.hooks.doAction('user_registered', 'user_123');
+```
+
+### 4. Mount an Orbit
+
+Orbits are just standard Photon applications that plug into the core.
+
+```typescript
+import { Photon } from '@gravito/photon';
+
+const blogOrbit = new Photon();
+blogOrbit.get('/posts', (c) => c.json({ posts: [] }));
+
+// Mount the orbit to /api/blog
+core.mountOrbit('/api/blog', blogOrbit);
+```
+
+### 5. Liftoff! 🚀
+
+```typescript
+// Export for Bun.serve
+export default core.liftoff(); // Automatically uses PORT from config/env
+```
+
+### 6. Process-level Error Handling (Recommended)
+
+Request-level errors are handled by `PlanetCore` automatically, but background jobs and startup code can still fail outside the request lifecycle.
+
+```ts
+// Register `unhandledRejection` / `uncaughtException`
+const unregister = core.registerGlobalErrorHandlers()
+
+// Optional: report to Sentry / custom reporter
+core.hooks.addAction('processError:report', async (ctx) => {
+  // ctx.kind: 'unhandledRejection' | 'uncaughtException'
+  // ctx.error: unknown
+})
+```
+
+## 📖 API Reference
+
+### `PlanetCore`
+
+- **`constructor(options?)`**: Initialize the core with optional Logger and Config.
+- **`register(provider: ServiceProvider)`**: Register a service provider.
+- **`bootstrap()`**: Boot all registered providers.
+- **`mountOrbit(path: string, app: Photon)`**: Mount a Photon app to a sub-path.
+- **`liftoff(port?: number)`**: Returns the configuration object for `Bun.serve`.
+- **`container`**: Access the IoC Container.
+- **`app`**: Access the internal Photon instance.
+- **`hooks`**: Access the HookManager.
+- **`logger`**: Access the Logger instance.
+- **`config`**: Access the ConfigManager.
+
+### `Container`
+
+- **`bind(key, factory)`**: Register a transient binding.
+- **`singleton(key, factory)`**: Register a shared binding.
+- **`make<T>(key)`**: Resolve a service instance.
+- **`instance(key, instance)`**: Register an existing object instance.
+- **`has(key)`**: Check if a service is bound.
+
+### `HookManager`
+
+- **`addFilter(hook, callback)`**: Register a filter.
+- **`applyFilters(hook, initialValue, ...args)`**: Execute filters sequentially.
+- **`addAction(hook, callback)`**: Register an action.
+- **`doAction(hook, ...args)`**: Execute actions.
+
+### `ConfigManager`
+
+- **`get(key, default?)`**: Retrieve a config value.
+- **`set(key, value)`**: Set a config value.
+- **`has(key)`**: Check if a config key exists.
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!
+Feel free to check the [issues page](https://github.com/gravito-framework/gravito/issues).
+
+## 📝 License
+
+MIT © [Carl Lee](https://github.com/gravito-framework/gravito)

package/README.zh-TW.md

@@ -0,0 +1,24 @@
+# @gravito/core
+
+> Galaxy 架構的微核心，基於 Photon 與 Bun 的輕量可擴充框架核心。
+
+## 安裝
+
+```bash
+bun add @gravito/core
+```
+
+## 快速開始
+
+```typescript
+import { PlanetCore } from '@gravito/core'
+
+const core = new PlanetCore({
+  config: {
+    PORT: 4000,
+    DEBUG: true
+  }
+})
+
+export default core.liftoff()
+```

package/dist/compat.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/compat.ts
+var compat_exports = {};
+module.exports = __toCommonJS(compat_exports);

package/dist/compat.d.cts

@@ -0,0 +1,313 @@
+/**
+ * @fileoverview Core HTTP Types for Gravito Framework
+ *
+ * These types provide a unified abstraction layer that decouples the framework
+ * from any specific HTTP engine (Photon, Express, custom, etc.).
+ *
+ * @module @gravito/core/http
+ * @since 2.0.0
+ */
+declare global {
+    interface ExecutionContext {
+        waitUntil(promise: Promise<unknown>): void;
+        passThroughOnException(): void;
+    }
+}
+/**
+ * Standard HTTP methods supported by Gravito
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * HTTP status codes
+ */
+type StatusCode = number;
+/**
+ * Content-bearing HTTP status codes (excludes 1xx, 204, 304)
+ */
+type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 304>;
+/**
+ * Base context variables available in every request
+ * Orbits can extend this interface via module augmentation
+ *
+ * @example
+ * ```typescript
+ * // Extending variables in your orbit:
+ * declare module '@gravito/core' {
+ *   interface GravitoVariables {
+ *     myService: MyService
+ *   }
+ * }
+ * ```
+ */
+interface GravitoVariables {
+    /**
+     * The PlanetCore instance
+     * @remarks Always available in PlanetCore-managed contexts
+     */
+    core?: unknown;
+    /**
+     * Logger instance
+     */
+    logger?: unknown;
+    /**
+     * Configuration manager
+     */
+    config?: unknown;
+    /**
+     * Cookie jar for managing response cookies
+     */
+    cookieJar?: unknown;
+    /**
+     * URL generator helper
+     */
+    route?: (name: string, params?: Record<string, unknown>, query?: Record<string, unknown>) => string;
+    [key: string]: unknown;
+}
+/**
+ * Validated request data targets
+ */
+type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie';
+/**
+ * GravitoRequest - Unified request interface
+ *
+ * Provides a consistent API for accessing request data regardless of
+ * the underlying HTTP engine.
+ *
+ * @example
+ * ```typescript
+ * const userId = ctx.req.param('id')
+ * const search = ctx.req.query('q')
+ * const body = await ctx.req.json<CreateUserDto>()
+ * ```
+ */
+interface GravitoRequest {
+    /** Full request URL */
+    readonly url: string;
+    /** HTTP method (uppercase) */
+    readonly method: string;
+    /** Request path without query string */
+    readonly path: string;
+    /**
+     * Get a route parameter value
+     * @param name - Parameter name (e.g., 'id' for route '/users/:id')
+     */
+    param(name: string): string | undefined;
+    /**
+     * Get all route parameters
+     */
+    params(): Record<string, string>;
+    /**
+     * Get a query string parameter
+     * @param name - Query parameter name
+     */
+    query(name: string): string | undefined;
+    /**
+     * Get all query parameters
+     */
+    queries(): Record<string, string | string[]>;
+    /**
+     * Get a request header value
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Get all request headers
+     */
+    header(): Record<string, string>;
+    /**
+     * Parse request body as JSON
+     * @throws {Error} If body is not valid JSON
+     */
+    json<T = unknown>(): Promise<T>;
+    /**
+     * Parse request body as text
+     */
+    text(): Promise<string>;
+    /**
+     * Parse request body as FormData
+     */
+    formData(): Promise<FormData>;
+    /**
+     * Parse request body as ArrayBuffer
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Parse form data (urlencoded or multipart)
+     */
+    parseBody<T = unknown>(): Promise<T>;
+    /**
+     * Get the raw Request object
+     */
+    readonly raw: Request;
+    /**
+     * Get validated data from a specific source
+     * @param target - The validation target
+     * @throws {Error} If validation was not performed for this target
+     */
+    valid<T = unknown>(target: ValidationTarget): T;
+}
+/**
+ * GravitoContext - Unified request context
+ *
+ * This interface encapsulates all HTTP request/response operations,
+ * enabling seamless replacement of the underlying HTTP engine.
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * // In a controller
+ * async show(ctx: GravitoContext) {
+ *   const id = ctx.req.param('id')
+ *   const user = await User.find(id)
+ *   return ctx.json({ user })
+ * }
+ * ```
+ */
+interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
+    /** The incoming request */
+    readonly req: GravitoRequest;
+    /**
+     * Send a JSON response
+     * @param data - Data to serialize as JSON
+     * @param status - HTTP status code (default: 200)
+     */
+    json<T>(data: T, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a plain text response
+     * @param text - Text content
+     * @param status - HTTP status code (default: 200)
+     */
+    text(text: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send an HTML response
+     * @param html - HTML content
+     * @param status - HTTP status code (default: 200)
+     */
+    html(html: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a redirect response
+     * @param url - Target URL
+     * @param status - Redirect status code (default: 302)
+     */
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    /**
+     * Create a Response with no body
+     * @param status - HTTP status code
+     */
+    body(data: BodyInit | null, status?: StatusCode): Response;
+    /**
+     * Stream a response
+     * @param stream - ReadableStream to send
+     * @param status - HTTP status code (default: 200)
+     */
+    stream(stream: ReadableStream, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a 404 Not Found response
+     */
+    notFound(message?: string): Response;
+    /**
+     * Send a 403 Forbidden response
+     */
+    forbidden(message?: string): Response;
+    /**
+     * Send a 401 Unauthorized response
+     */
+    unauthorized(message?: string): Response;
+    /**
+     * Send a 400 Bad Request response
+     */
+    badRequest(message?: string): Response;
+    /**
+     * Set a response header
+     * @param name - Header name
+     * @param value - Header value
+     * @param options - Options (append: true to add multiple values)
+     */
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    /**
+     * Get a request header
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Set the response status code
+     * @param code - HTTP status code
+     */
+    status(code: StatusCode): void;
+    /**
+     * Get a context variable
+     * @param key - Variable key
+     */
+    get<K extends keyof V>(key: K): V[K];
+    /**
+     * Set a context variable
+     * @param key - Variable key
+     * @param value - Variable value
+     */
+    set<K extends keyof V>(key: K, value: V[K]): void;
+    /**
+     * Get the execution context (for Cloudflare Workers, etc.)
+     */
+    readonly executionCtx?: ExecutionContext;
+    /**
+     * Get environment bindings (for Cloudflare Workers, etc.)
+     */
+    readonly env?: Record<string, unknown>;
+    /**
+     * Access the native context object from the underlying HTTP engine.
+     *
+     * ⚠️ WARNING: Using this ties your code to a specific adapter.
+     * Prefer using the abstraction methods when possible.
+     *
+     * @example
+     * ```typescript
+     * // Only when absolutely necessary
+     * const photonCtx = ctx.native as Context // Photon Context
+     * ```
+     */
+    readonly native: unknown;
+}
+/**
+ * Next function for middleware chain
+ */
+type GravitoNext = () => Promise<void>;
+/**
+ * GravitoHandler - Standard route handler type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const handler: GravitoHandler = async (ctx) => {
+ *   return ctx.json({ message: 'Hello, World!' })
+ * }
+ * ```
+ */
+type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * GravitoMiddleware - Standard middleware type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const logger: GravitoMiddleware = async (ctx, next) => {
+ *   console.log(`${ctx.req.method} ${ctx.req.path}`)
+ *   await next()
+ * }
+ * ```
+ */
+type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | undefined | Promise<Response | undefined | undefined>;
+/**
+ * Error handler type
+ */
+type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * Not found handler type
+ */
+type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+
+export type { ContentfulStatusCode, GravitoContext as Context, GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNext, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, GravitoHandler as Handler, HttpMethod, GravitoMiddleware as MiddlewareHandler, GravitoNext as Next, StatusCode, ValidationTarget, GravitoVariables as Variables };