@scarletgeek/web-kernel 1.0.0

package/example/programs/myprogram.js

@@ -0,0 +1,9 @@
+export default class MyProgram {
+    onStart(args) {
+        console.log("My Program is started :: ", args);
+    }
+
+    onDestroy() {
+        console.log("My Program is destroyed");
+    }
+}

package/example/programs/register.js

@@ -0,0 +1,7 @@
+import MyProgram from "./myprogram.js";
+
+export function registerPrograms(kernel) {
+    kernel.registerPrograms({
+        "my-program": MyProgram
+    });
+}

package/example/requests/getposts.js

@@ -0,0 +1,23 @@
+import { Request } from "/dist/index.js";
+
+export default class GetPosts extends Request {
+    get url() {
+        return "https://jsonplaceholder.typicode.com/posts";
+    }
+
+    get method() {
+        return "GET";
+    }
+    
+    onProcessing() {
+        console.log("Get posts is processing");
+    }
+
+    onSuccess(response) {
+        console.log("Get posts is success :: ", response);
+    }
+
+    onError(error) {
+        console.error("Get Posts is error :: ", error);
+    }
+}

package/example/requests/register.js

@@ -0,0 +1,7 @@
+import GetPosts from "./getposts.js";
+
+export function registerRequests(kernel) {
+    kernel.registerRequests({
+        "getposts" : GetPosts
+    });
+}

package/example/script.js

@@ -0,0 +1,50 @@
+import { registerPrograms } from "./programs/register.js";
+import { registerRequests } from "./requests/register.js";
+import { Kernel } from "/dist/index.js";
+
+// Initiate kernel
+window.kernel = new Kernel();
+
+// Programs
+registerPrograms(window.kernel);
+
+window.kernel.onBoot((k) => {
+    k.start("my-program", {
+        message: "Kernel is booted.",
+    });
+})
+
+// window.kernel.start("my-program", {
+//     message: "Message is registered."
+// });
+
+document.getElementById("link-button").addEventListener("click", () => window.kernel.destroy("my-program"));
+
+
+// Events
+window.kernel.on("kernel:test", (e) => {
+    console.log("Kernel test event fired :: ", e.detail);
+});
+
+document.getElementById("second-link-button").addEventListener("click", () => {
+    window.kernel.emit("kernel:test", {
+        name: "Naruto Uzumaki",
+        age: 18,
+        residence: "Konoha village"
+    });
+});
+
+// Requests
+registerRequests(window.kernel);
+
+document.getElementById("trail-button").addEventListener("click", () => {
+    window.kernel.send("getposts");
+});
+
+document.getElementById("metrics-button").addEventListener("click", () => {
+    window.kernel.metrics();
+});
+
+document.addEventListener("DOMContentLoaded", () => {
+    window.kernel.boot();
+});

package/mix-manifest.json

@@ -0,0 +1,3 @@
+{
+    "/dist/index.js": "/dist/index.js"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@scarletgeek/web-kernel",
+    "version": "1.0.0",
+    "description": "A kernel for web to handle scripting",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "directories": {
+        "example": "example"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/thescarletgeek/web-kernel"
+    },
+    "scripts": {
+        "dev": "npm run development",
+        "development": "mix",
+        "watch": "mix watch",
+        "watch-poll": "mix watch -- --watch-options-poll=1000",
+        "hot": "mix watch --hot",
+        "prod": "npm run production",
+        "production": "mix --production"
+    },
+    "keywords": [
+        "kernel",
+        "web-kernel",
+        "opensource",
+        "webjs"
+    ],
+    "author": "",
+    "license": "MIT",
+    "devDependencies": {
+        "laravel-mix": "^6.0.49",
+        "ts-loader": "^9.5.4",
+        "typescript": "^5.9.3"
+    },
+    "homepage": "https://github.com/thescarletgeek/web-kernel",
+    "bugs": {
+        "url": "https://github.com/thescarletgeek/web-kernel/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/readme.md

@@ -0,0 +1,221 @@
+# Web Kernel
+Web Kernel is an experimental runtime layer inspired by the core concepts of operating system kernels. While it is not a real kernel, it is designed to feel like one, focusing on structure, control and clarity without relying on shiny frameworks.
+
+The idea originated while I am studying how OS kernels manage processes, states and system coordination.
+
+As applications grow, scripting often becomes duplicated, tightly coupled, and hard to reason about. Web kernel explores whether a central control layer can manage programs, events and requests in a structured and predictable manner, while keeping the system minimal and extensible.
+
+## Philosophy
+- Structure programs, events, and requests without relying on frameworks.
+- Enable scripting using Javascript/Typescript.
+- Reduce duplication in execution and orchestration logic.
+- Follow lifecycle-based design for programs and requests.
+
+## What web kernel is (and isn't)
+### What it is
+- A runtime coordination layer.
+- A structured way to manage programs.
+- A state-aware execution controller.
+- A foundation for custom architecture.
+
+### What it is not
+- A web framework.
+- A replacement for React, Vue, Express, etc.
+- A dependency-heavy abstraction layer.
+- A magic solution for bad architecture.
+
+---
+## Quickstart
+To install web kernel, either install through npm or directly incldue the script.
+
+Install through **npm** :
+```
+npm install @scarletgeek/web-kernel
+```
+
+To initialize the kernel :
+
+```js
+import { Kernel } from "@scarletgeek/web-kernel";
+
+// Initialize the kernel
+window.kernel = new Kernel();
+
+// Run programs on boot
+window.kernel.onBoot((k) => {
+    k.start("program-name");
+});
+
+// Run boot() method to boot the kernel
+document.addEventListener("DOMContentLoaded", () => {
+    window.kernel.boot();
+});
+```
+
+---
+## Programs
+Programs are first-class execution units, similar to processes in an OS.
+
+**Each Program :**
+- Has a defined lifecycle.
+- Can be executed, tracked and observed.
+- Exists independently of framework logic.
+
+To create and initialize programs :
+
+```js
+export default class MyProgram {
+    onStart(args) {
+        console.log("My Program is started :: ", args);
+    }
+
+    onDestroy() {
+        console.log("My Program is destroyed");
+    }
+}
+```
+
+```js
+// Register programs by passing program object and a name.
+window.kernel.registerPrograms({
+    "program-name": MyProgram
+});
+```
+
+Run programs from kernel :
+
+```js
+// Run program using kernel
+// Arguments can be passed in start() method.
+// Arguments are optional
+window.kernel.start("program-name", {})
+```
+Run programs on kernel startup :
+
+```js
+// Run programs on startup using onBoot() method
+window.kernel.onBoot((k) => {
+    k.start("program--name");
+});
+```
+
+---
+
+## Events
+
+- Events represent signals within the system.
+- Used to communicate between programs without tight coupling.
+- Help reduce duplication in cross-program communication.
+
+Fire events from kernel :
+```js
+// Fire events using kernel
+window.kernel.emit("kernel:test", {
+    name: "Naruto Uzumaki",
+    age: 18,
+    residence: "Konoha village"
+});
+```
+
+To listen to events from kernel :
+```js
+// Add event listener
+const listener = window.kernel.on("kernel:test", (e) => {
+    console.log("Kernel test event fired :: ", e.detail);
+});
+
+// Remove the defined listener
+listener();
+
+// To listen to event only once
+window.kernel.once("kernel:test", (e) => {
+    console.log("Kernel test event fired :: ", e.detail);
+});
+```
+
+---
+
+## Request
+Requests can be used for API calls.
+
+**Request Types** :
+
+- GET
+- POST
+- PUT
+- PATCH
+- DELETE
+
+Create Request :
+
+```js
+import { Request } from "/dist/index.js";
+
+export default class GetPosts extends Request {
+    get url() {
+        return "https://jsonplaceholder.typicode.com/posts";
+    }
+
+    get method() {
+        return "GET";
+    }
+
+    get headers() {
+        // Headers can be defined here
+        return {}
+    }
+
+    get payload() {
+        // Request payload can be defined here
+        return {}
+    }
+    
+    onProcessing() {
+        // Runs while request is running
+        console.log("Get posts is processing");
+    }
+
+    onSuccess(response) {
+        // When request is succeeded
+        console.log("Get posts is success :: ", response);
+    }
+
+    onError(error) {
+        // When request is error
+        console.error("Get Posts is error :: ", error);
+    }
+}
+
+```
+
+Register request on kernel :
+
+```js
+window.kernel.registerRequest({
+    "get-posts": GetPosts
+});
+```
+
+Run request using kernel :
+
+```js
+window.kernel.send("get-posts");
+```
+
+---
+
+## Contributing
+
+Web kernel is an experimental project. Contributions are welcome for experimentation, improvements, and exploration of ideas.
+
+1. Fork the repository
+2. Create a new branch from **develop**.
+3. Make your changes with clear, focused commits.
+4. Ensure existing functionality is not broken.
+5. Submit a pull request to the **develop** branch.
+6. Describe what has changed and why.
+
+---
+## License
+
+[MIT License](https://opensource.org/license/MIT)

package/src/KernelEvents.ts

@@ -0,0 +1,42 @@
+import { IEventMap, IEventHandler, IUnsubscribeEvent } from "./types/IKernel";
+
+class KernelEvents extends EventTarget {
+    on<K extends keyof IEventMap>(
+        type: K,
+        handler: IEventHandler<IEventMap[K]>,
+        options?: AddEventListenerOptions
+    ): IUnsubscribeEvent {
+        this.addEventListener(type, handler, options);
+
+        return () => this.off(type, handler);
+    }
+
+    once<K extends keyof IEventMap>(
+        type: K,
+        handler: IEventHandler<IEventMap[K]>
+    ) {
+        this.addEventListener(type, handler, {
+            once: true
+        });
+    }
+
+    off<K extends keyof IEventMap>(
+        type: K,
+        handler: IEventHandler<IEventMap[K]>
+    ) {
+        this.removeEventListener(type, handler);
+    }
+
+    emit<K extends keyof IEventMap>(
+        type: K,
+        detail: IEventMap[K] = {}
+    ) {
+        return this.dispatchEvent(new CustomEvent(type, { detail }));
+    }
+
+    destroy() {
+        // this.replaceWith?.(null);
+    }
+}
+
+export default KernelEvents;

package/src/ProgramHandler.ts

@@ -0,0 +1,106 @@
+import { ProgramState } from "./types/IKernel";
+import { logger, LoggerLevel } from "./utils";
+
+class ProgramHandler {
+    private programs = new Map();
+    private programState = new Map();
+
+    constructor() {
+        //
+    }
+
+    isProgramExists(key: string) {
+        return (this.programs.has(key) && this.programState.has(key));
+    }
+
+    addProgram(key: string, program: any) {
+        if(this.programs.has(key)) {
+            logger(LoggerLevel.WARNING, `Program ${key} already exists.`);
+            return;
+        }
+
+        this.programs.set(key, new program());
+        this.programState.set(key, ProgramState.IDLE);
+    }
+
+    startProgram(key: string, args: any = null) {
+        const program = this.programs.get(key);
+        if(!program) {
+            logger(LoggerLevel.WARNING, `Program ${key} not found.`);
+            return;
+        }
+
+        const status = this.programState.get(key);
+        if(status === ProgramState.RUNNING) {
+            logger(LoggerLevel.WARNING, `Program ${key} is already running.`);
+            return;
+        }
+
+        if(typeof program.onStart !== "function") {
+            logger(LoggerLevel.ERROR, `onStart method is not defined in the program ${key}.`);
+            return;
+        }
+
+        try {
+            program.onStart(args);
+            this.programState.set(key, ProgramState.RUNNING);
+        } catch(error) {
+            this.programState.set(key, ProgramState.ERROR);
+            logger(LoggerLevel.ERROR, `Error occured in program ${key} - `, error);
+        }
+    }
+
+    endProgram(key: string) {
+        const program = this.programs.get(key);
+        if(!program) {
+            logger(LoggerLevel.WARNING, `Program ${key} not found.`);
+            return;
+        }
+
+        if(this.programState.get(key) !== ProgramState.RUNNING) {
+            logger(LoggerLevel.WARNING, `Program ${key} is not running.`);
+            return;
+        }
+
+        if(typeof program.onDestroy !== "function") {
+            logger(LoggerLevel.ERROR, `onDestroy method is not defined in the program ${key}.`);
+            return;
+        }
+        
+        try {
+            program.onDestroy();
+            this.programState.set(key, ProgramState.STOPPED);
+        } catch(error) {
+            this.programState.set(key, ProgramState.ERROR);
+            logger(LoggerLevel.ERROR, `Error occured in program ${key} - `, error);
+        }
+    }
+
+    getProgramsByState(programState: ProgramState) {
+        const status: any = {};
+
+        for(const [key, state] of this.programState) {
+            if(state === programState) {
+                status[key] = state;
+            }
+        }
+
+        return status;
+    }
+
+    getAllProgramStatus() {
+        const status: any = {};
+
+        for(const [key, state] of this.programState) {
+            status[key] = state;
+        }
+
+        return status;
+    }
+
+    getProgramStatus(key: string) {
+        return this.programs.get(key);
+    }
+}
+
+export default ProgramHandler;

package/src/RequestHandler.ts

@@ -0,0 +1,31 @@
+import { fetchAdapter } from "./request/adapters";
+import Request from "./request/Request";
+import { IKernelRequest } from "./types/IKernel";
+import { logger, LoggerLevel } from "./utils";
+
+class RequestHandler {
+    requests: IKernelRequest = {};
+
+    addRequest(key: string, RequestClass: any) {
+        const instance = new RequestClass(fetchAdapter);
+        if(!(instance instanceof Request)) {
+            throw new Error(`Invalid request "${key}". It must extend kernel Request class.`);
+        }
+        
+        this.requests[key] = instance;
+    }
+
+    startRequest(key: string) {
+        if(!this.requests[key]) {
+            logger(LoggerLevel.WARNING, "Request not found.");
+        }
+
+        if(typeof this.requests[key].send !== "function") {
+            logger(LoggerLevel.ERROR, "Send method not available for the request.");
+        }
+
+        this.requests[key].send();
+    }
+}
+
+export default RequestHandler;

package/src/index.ts

@@ -0,0 +1,10 @@
+import Kernel from "./kernel";
+import Request from "./request/Request"; 
+
+import { LoggerLevel } from "./utils";
+
+export {
+    Kernel,
+    LoggerLevel,
+    Request
+};

package/src/kernel.ts

@@ -0,0 +1,94 @@
+import ProgramHandler from "./ProgramHandler";
+import { IKernelProgram, IEventMap, IEventHandler, IUnsubscribeEvent, IKernelRequest, KernelState } from "./types/IKernel";
+import KernelEvents from "./KernelEvents";
+import RequestHandler from "./RequestHandler";
+
+class Kernel {
+    programHandler;
+    eventHandler;
+    requestHandler;
+    state: KernelState;
+    bootHandlers: any[];
+    
+    constructor() {
+        this.programHandler = new ProgramHandler();
+        this.eventHandler = new KernelEvents();
+        this.requestHandler = new RequestHandler();
+        this.state = KernelState.CREATED;
+        this.bootHandlers = [];
+    }
+
+    onBoot(callback: any) {
+        if(this.state == KernelState.BOOTED) {
+            callback(this);
+            return;
+        }
+
+        this.bootHandlers.push(callback);
+    }
+
+    boot() {
+        if(this.state !== KernelState.CREATED) {
+            return;
+        }
+
+        this.state = KernelState.BOOTING;
+
+        for(const handler of this.bootHandlers) {
+            handler(this);
+        }
+
+        this.bootHandlers.length = 0;
+        this.state = KernelState.BOOTED;
+    }
+
+    registerPrograms(programs: IKernelProgram) {
+        if(Object.keys(programs).length) {
+            Object.keys(programs).forEach(key => {
+                this.programHandler.addProgram(key, programs[key]);
+            })
+        }
+    }
+
+    start(programName: string, args: any = null) {
+        this.programHandler.startProgram(programName, args);
+    }
+
+    destroy(programName: string) {
+        this.programHandler.endProgram(programName);
+    }
+
+    emit<K extends keyof IEventMap>(type: K, detail: IEventMap[K] = {}) {
+        this.eventHandler.emit(type, detail);
+    }
+
+    on<K extends keyof IEventMap>(type: K, handler: IEventHandler<IEventMap[K]>, options?: AddEventListenerOptions) {
+        return this.eventHandler.on(type, handler, options);
+    }
+
+    once<K extends keyof IEventMap>(type: K, handler: IEventHandler<IEventMap[K]>) {
+        this.eventHandler.once(type, handler);
+    }
+
+    registerRequests(requests: IKernelRequest) {
+        if(Object.keys(requests).length) {
+            Object.keys(requests).forEach(key => {
+                this.requestHandler.addRequest(key, requests[key]);
+            });
+        }
+    }
+
+    send(key: string) {
+        this.requestHandler.startRequest(key);
+    }
+
+    status() {
+        const data: any = {};
+
+        data["programs"] = this.programHandler.getAllProgramStatus();
+
+        console.log(data);
+    }
+}
+
+export default Kernel;

package/src/request/DataTransformer.ts

@@ -0,0 +1,19 @@
+import { ResponseTransformer } from "./interfaces";
+
+class DataTransformer<T = Response> implements ResponseTransformer<T> {
+    async transform(response: Response): Promise<T> {
+        const contentType = response.headers.get("content-type") || "";
+
+        if(contentType.includes("application/json")) {
+            return await response.json();
+        }
+
+        if(contentType.includes("text/")) {
+            return await response.text() as unknown as T;
+        }
+
+        return await response.blob() as unknown as T;
+    }
+}
+
+export default DataTransformer;