@hamim_4444/pulsar 0.0.0-stage → 1.0.0

package/dist/types/engine.types.d.ts

@@ -0,0 +1,115 @@
+export type EnginePoolingMode = 'interval-driven-pooler' | 'event-driven-pooler';
+export type EngineSelfInvocation = {
+    selfURL: string;
+    selfInvocationMethod?: "auto_using_pgnet";
+} | {
+    selfURL: string;
+    selfInvocationMethod?: "manual";
+    handler: (selfUrl: string) => Promise<void> | void;
+};
+type BaseEngineOptions = {
+    /**
+     * The global maximum ceiling for total tick executions across ALL queues in a single execution run.
+     *
+     * Once the cumulative number of ticks executed across all queues reaches this limit,
+     * the engine terminates the current execution cycle and triggers a self-invocation restart.
+     *
+     * ### Execution Flow:
+     * ```
+     * [ Queue Ticks Executed ] ──(Count reaches cycleTickLimit)──> [ Terminate Cycle & Self-Invoke ]
+     * ```
+     *
+     * For example, with 10 queues and `cycleTickLimit: 10`, each queue executes 1 tick before
+     * the engine reaches the global limit and restarts, ensuring no single queue consumes
+     * the entire execution window.
+     *
+     * @default Infinity
+    */
+    cycleTickLimit?: number;
+    /**
+     * Controls the execution strategy for dispatching tick cycles across target queues.
+     *
+     * This setting dictates whether the engine evaluates and triggers ticks across multiple
+     * configured queues sequentially (one queue at a time) or in parallel (simultaneously).
+     *
+     * ### Execution Flow Comparison:
+     *
+     * **`sequential` (Default - CPU & Memory Safe):**
+     * ```
+     * [ Queue A Tick ] ──(await completion)──> [ Queue B Tick ] ──(await completion)──> [ Queue C Tick ]
+     * ```
+     * * **Behavior:** Processes queue ticks strictly one after another in serial order.
+     * * **Pros:** Keeps CPU usage steady and avoids sudden spike loads on database connections and memory isolates.
+     * * **Cons:** Takes longer total clock time to complete a single tick cycle across all queues.
+     *
+     * **`parallel` (High Throughput - Higher Resource Demand):**
+     * ```
+     * ┌─> [ Queue A Tick ]
+     * ├─> [ Queue B Tick ]  ─── (Fired simultaneously via Promise.allSettled)
+     * └─> [ Queue C Tick ]
+     * ```
+     * * **Behavior:** Dispatches tick evaluations for all candidate queues at the exact same moment.
+     * * **Pros:** Dramatically lowers cycle latency and maximizes total job processing throughput.
+     * * **Cons:** Produces concurrent CPU spikes, higher transient V8 memory allocations, and heavier concurrent database query bursts.
+     *
+     * > **Performance Note:** Choosing between `sequential` and `parallel` directly impacts engine resource utilization.
+     * > In environments with strict CPU time allocations or tight database connection limits, `sequential` prevents resource starvation.
+     * > For high-capacity environments prioritizing low dispatch latency across many queues, `parallel` delivers optimal speed.
+     *
+     * @default "sequential"
+     */
+    tickConcurrency?: "parallel" | "sequential";
+    /**
+     * How often (in seconds) the engine checks its own internal health and runtime state.
+     *
+     * @default 15
+     */
+    healthCheckIntervalSec?: number;
+};
+export type SelfInvokingEngine = BaseEngineOptions & {
+    selfURL: string;
+    selfInvocationMethod?: "auto_using_pgnet" | {
+        method: "manual";
+        handler: (selfUrl: string) => Promise<void> | void;
+    };
+    /**
+     * Specifies how often (in seconds) the engine should invoke itself.
+     *
+     * The minimum value is **1 second**. A higher number increases the delay
+     * between self-invocations.
+     *
+     * ### Recommendations & Workload Pacing
+     * * It is generally **recommended to keep the default (1 second)**.
+     * * Increasing this value introduces processing latency before jobs are picked up.
+     * * **Lower values (e.g., 1s)** process jobs faster and are recommended if you have
+     *   multiple interval-driven queues with frequent, predictable workloads.
+     * * **Higher values (e.g., 5s)** process jobs slower but significantly reduce the
+     *   total number of engine invocations over time.
+     *
+     * ### Estimated Monthly Invocations
+     * The lower this setting is, the higher the total invocation count will be at the
+     * end of the month.
+     *
+     * **1 Second Interval:**
+     * * Formula: `1 second * 60 seconds * 60 minutes * 24 hours * 30 days`
+     * * Total: **~2,592,000 invocations / month**
+     *
+     * **5 Seconds Interval:**
+     * * Formula: `(1 second / 5) * 60 seconds * 60 minutes * 24 hours * 30 days`
+     * * Total: **~518,400 invocations / month**
+     *
+     * *(Note: Depending on your hosting platform, actual invocation counts may be slightly
+     * higher or lower based on execution overhead).*
+     *
+     * @default 1
+     * @minimum 1
+    */
+    selfInvocationIntervalSec?: number;
+    selfRestartIntervalSec?: number;
+};
+export type PersistentEngine = BaseEngineOptions & {
+    poolingMode?: EnginePoolingMode;
+    poolingIntervalMS?: number;
+};
+export {};
+//# sourceMappingURL=engine.types.d.ts.map

package/dist/types/engine.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.types.d.ts","sourceRoot":"","sources":["../../src/types/engine.types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;AAEjF,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAG,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAG,kBAAkB,CAAA;CAAE,GAChE;IAAE,OAAO,EAAG,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAG,QAAQ,CAAC;IAAC,OAAO,EAAG,CAAC,OAAO,EAAG,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAAA;AAuGhH,KAAK,iBAAiB,GAAG;IACrB;;;;;;;;;;;;;;;;MAgBE;IACF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,eAAe,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IAC5C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,kBAAkB,GAAG;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;IACrH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA+BE;IACF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IAC/C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAA"}

package/dist/types/eventTriggerStrategry.types.d.ts

@@ -0,0 +1,34 @@
+export declare enum EventTriggerStrategy {
+    /**
+     * Uses PostgreSQL LISTEN/NOTIFY (PG Notify) for real-time event-driven queue triggering.
+     *
+     * **How it works:** The engine establishes a persistent subscription to a database channel.
+     * When an event occurs, Postgres broadcasts an instant notification, triggering the queues
+     * immediately with minimal latency and zero polling overhead.
+     *
+     * **Crucial Infrastructure Requirement:** This strategy **requires a direct, persistent TCP
+     * connection URL** provided to the Postgres driver. If your database infrastructure uses serverless
+     * proxies, restricted connection pools, or environments that do not support long-lived TCP socket
+     * listeners (LISTEN/NOTIFY state), this strategy will fail to receive events.
+     */
+    POSTGRES_NOTIFY = "POSTGRES_NOTIFY",
+    /**
+     * Uses an external HTTP webhook driven directly by the database (`pg_net`).
+     *
+     * **How it works:** This strategy requires an accessible HTTP endpoint to be exposed on the
+     * running container or machine. When an event occurs, Postgres utilizes the built-in `pg_net`
+     * extension to fire an outbound HTTP request directly to this endpoint, which in turn invokes
+     * and executes the event-driven queues.
+     */
+    WEBHOOK = "WEBHOOK",
+    /**
+     * Uses a database-backed table polling mechanism.
+     *
+     * **How it works:** Completely independent of persistent TCP notification sockets or HTTP
+     * endpoints. Instead, event producers insert new task rows directly into a designated
+     * subscription table. The engine periodically polls this table at a configured interval
+     * (e.g., every 500ms) to scan for new rows, process them, and trigger the respective queues.
+     */
+    POLLING = "POLLING"
+}
+//# sourceMappingURL=eventTriggerStrategry.types.d.ts.map

package/dist/types/eventTriggerStrategry.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventTriggerStrategry.types.d.ts","sourceRoot":"","sources":["../../src/types/eventTriggerStrategry.types.ts"],"names":[],"mappings":"AAAA,oBAAY,oBAAoB;IAC5B;;;;;;;;;;;OAWG;IACH,eAAe,oBAAoB;IAEnC;;;;;;;OAOG;IACH,OAAO,YAAY;IAEnB;;;;;;;OAOG;IACH,OAAO,YAAY;CACtB"}

package/dist/types/integrations.types.d.ts

@@ -0,0 +1,16 @@
+import type { PulsarEventsIntegrations, PulsarLoggerIntegrations } from "../integrations";
+import type { PulsarCore } from "../service/PulsarBaseService";
+export interface IIntegration {
+    module: "API" | "EVENTS" | "LOGGER";
+    main: (engine: PulsarCore) => Promise<void>;
+}
+export interface IntegrationMap {
+    LOGGER: PulsarLoggerIntegrations;
+    API: any;
+    EVENTS: PulsarEventsIntegrations;
+}
+export type IntegrationConstructor = new (access: string) => IIntegration;
+export interface HostOptions {
+    integrations?: Array<IntegrationConstructor | IIntegration>;
+}
+//# sourceMappingURL=integrations.types.d.ts.map

package/dist/types/integrations.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrations.types.d.ts","sourceRoot":"","sources":["../../src/types/integrations.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,MAAM,WAAW,YAAY;IACzB,MAAM,EAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,CAAC,MAAM,EAAG,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAG,wBAAwB,CAAC;IAClC,GAAG,EAAG,GAAG,CAAC;IACV,MAAM,EAAG,wBAAwB,CAAC;CACrC;AAED,MAAM,MAAM,sBAAsB,GAAG,KAAK,MAAM,EAAE,MAAM,KAAK,YAAY,CAAC;AAE1E,MAAM,WAAW,WAAW;IACxB,YAAY,CAAC,EAAG,KAAK,CAAC,sBAAsB,GAAG,YAAY,CAAC,CAAC;CAChE"}

package/dist/types/nebula.types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Operating execution mode for a Pulsar engine instance inside a Nebula cluster.
+ * Determines how the node handles global dynamic job spills versus dedicated queues.
+ */
+export type NebulaExecutionMode = 'exclusive' | 'shared' | 'hybrid';
+/**
+ * Connection transport strategy to communicate with the Nebula Control Plane.
+ * Supports multiple backends for high-availability cluster state synchronization.
+ */
+export interface NebulaConnectionConfig {
+    /** Target endpoint for HTTP/REST/RPC handshakes (e.g. VPS URL, Edge worker API) */
+    endpoint?: string;
+    /** Direct client connection for Redis-backed Nebula cluster state */
+    redisUrl?: string;
+    /** Direct DB client configuration for Postgres-backed cluster state */
+    postgresUrl?: string;
+    /** Bearer token or cluster secret key for engine-to-control-plane authentication */
+    authToken?: string;
+    /** Maximum timeout in milliseconds for control plane handshakes */
+    timeoutMs?: number;
+}
+/**
+ * Heartbeat, lease management, and health-reporting policy for this engine instance.
+ * Ensures orphaned workers are automatically reaped and locks are safely revoked.
+ */
+export interface NebulaHealthConfig {
+    /** Interval in milliseconds between heartbeat pings back to Nebula */
+    heartbeatIntervalMs: number;
+    /** Time-to-live for the instance lease in the central state store (seconds) */
+    leaseTtlSec: number;
+    /** Enable automatic lease revocation when the V8 isolate nears execution deadline */
+    revokeOnIsolateDeath: boolean;
+}
+/**
+ * Main Nebula configuration interface embedded directly in PulsarEngine setup.
+ * Coordinates static worker code registries with Nebula's dynamic control plane routing.
+ */
+export interface NebulaClusterConfig {
+    enabled: boolean;
+    /** Cluster name or prefix namespace to isolate environments (e.g. 'prod-eu-1') */
+    clusterId: string;
+    /**
+     * Defines whether this engine instance operates as an exclusive, shared, or hybrid process
+     * within the Nebula cluster, controlling how queues are assigned during handshakes:
+     * - **'exclusive'**: Locks the instance strictly to its pre-configured static queues (e.g., `q1`, `q2`).
+     *   Even during high traffic or load spikes, Nebula will never route any other queues to this instance.
+     * - **'shared'**: Allows Nebula to dynamically allocate any queues supported by this instance's
+     *   partition based on current cluster load, backlogs, and scheduling algorithms.
+     * - **'hybrid'**: Maintains primary dedicated queue assignments while permitting the node to absorb
+     *   fallback spillover capacity and overflow traffic whenever resources are idle.
+     */
+    assignmentScope: NebulaExecutionMode;
+    /** Transport configuration for communicating with Nebula */
+    connection: NebulaConnectionConfig;
+    /** Health check, lease TTL, and heartbeat options */
+    health: NebulaHealthConfig;
+    /**
+     * Strict queue allocation safety guard.
+     * If true, throws an error if local static queue configuration collides
+     * with assigned Nebula remote queues on startup.
+     */
+    strictIsolation?: boolean;
+    supportedPartitions?: string[];
+}
+//# sourceMappingURL=nebula.types.d.ts.map

package/dist/types/nebula.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nebula.types.d.ts","sourceRoot":"","sources":["../../src/types/nebula.types.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,QAAQ,GACR,QAAQ,CAAC;AAEb;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,sEAAsE;IACtE,mBAAmB,EAAE,MAAM,CAAC;IAE5B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IAEpB,qFAAqF;IACrF,oBAAoB,EAAE,OAAO,CAAC;CACjC;AAGD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAG,OAAO,CAAC;IAElB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,eAAe,EAAE,mBAAmB,CAAC;IAErC,4DAA4D;IAC5D,UAAU,EAAE,sBAAsB,CAAC;IAEnC,qDAAqD;IACrD,MAAM,EAAE,kBAAkB,CAAC;IAE3B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,mBAAmB,CAAC,EAAG,MAAM,EAAE,CAAC;CACnC"}

package/dist/types/queue.types.d.ts

@@ -0,0 +1,95 @@
+import type { TimingProfile, TimingProfileType } from "../static/TimingProfile.d.ts";
+import type { EnginePoolingMode } from "./engine.types.d.ts";
+export type EngineQueuesConfig = {
+    queue: string;
+    /**
+     * Configures the execution cadence and polling intervals for this queue.
+     *
+     * Accepts a predefined preset (`'REALTIME'`, `'STANDARD'`, `'BALANCED'`, `'RELAXED'`, `'ULTRA_EFFICIENT'`)
+     * or a custom `TimingProfile` object to fine-tune active, backoff, and idle delays.
+     *
+     * @default 'STANDARD'
+    */
+    profile: TimingProfileType | TimingProfile;
+    /**
+     * Controls how the queue pulls work from storage.
+     *
+     * - `'interval-driven-pooler'`: For steady, predictable background workloads that need ongoing processing.
+     * - `'event-driven-pooler'`: For instant processing of sporadic or bursty jobs while keeping idle execution costs at zero.
+     *
+     * @default 'interval-driven-pooler'
+    */
+    pooler: EnginePoolingMode;
+    /**  */
+    type: "fifo" | "STANDER";
+    /**
+     * Maximum concurrent worker instances allowed for this queue.
+     *
+     * @warning High concurrency increases parallel connections, I/O operations, and resource contention on the database and storage layer.
+    */
+    concurrency: number;
+    /** Number of jobs assigned per worker batch */
+    n: number;
+    /**
+     * Maximum aggregate jobs the engine can fetch in a single tick loop.
+     * If (concurrency * n) > maxJobsPerTick, active workers will be scaled
+     * down automatically to satisfy this limit (Backpressure throttling).
+     */
+    maxJobsPerTick?: number;
+    /**
+     * Defines the tick budget (quantum) allocated to this isolate. Once the tick count
+     * reaches this threshold, the engine marks the isolate's execution cycle as completed.
+     *
+     * @default 10
+     *
+     * @warning Do not set `cycleTickLimit` higher than 20 per queue, especially when running multiple queues.
+     * High tick limits keep execution pinned to the same serverless instance, escalating the risk
+     * of hitting total execution timeouts (e.g., AWS Lambda, Vercel, or Cloudflare Workers limits).
+    */
+    cycleTickLimit?: number;
+    sleep?: number;
+    /**
+        * Rules for automatically switching queue performance modes based on active workload.
+        *
+        * When a queue experiences sustained inactivity, the engine automatically transitions it
+        * into an idle state. This significantly reduces database read operations, lowers API and
+        * storage costs, and minimizes unnecessary CPU and network utilization during quiet periods.
+        *
+        * As soon as new jobs are detected, the engine instantly transitions back and restores
+        * the queue's original active timing profile without manual intervention or job delivery latency.
+        *
+     */
+    stateTransitionPolicy?: {
+        /**
+         * Whether automatic state switching is active for this queue.
+         *
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Number of consecutive empty ticks required before the engine transitions into idle mode for this queue.
+         *
+         * @default 10
+         */
+        idleThresholdTicks?: number;
+        /**
+         * The timing profile or custom interval object applied when the queue enters idle mode.
+         *
+         * Accepts a predefined preset (`'RELAXED'`, `'ULTRA_EFFICIENT'`) or a custom `TimingProfile`.
+         *
+         * maxTimerMs will be ignored
+         *
+         * @default 'RELAXED'
+         */
+        idleTimingProfile?: TimingProfileType | TimingProfile;
+    };
+    deadLetterQueue?: string;
+};
+export type QueueMessage<T = unknown> = {
+    msg_id: number;
+    read_ct: number;
+    enqueued_at: Date;
+    vt: Date;
+    message: T;
+};
+//# sourceMappingURL=queue.types.d.ts.map

package/dist/types/queue.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.types.d.ts","sourceRoot":"","sources":["../../src/types/queue.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,MAAM,kBAAkB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;MAOE;IACF,OAAO,EAAG,iBAAiB,GAAG,aAAa,CAAC;IAE5C;;;;;;;MAOE;IACF,MAAM,EAAG,iBAAiB,CAAC;IAE3B,OAAO;IACP,IAAI,EAAG,MAAM,GAAG,SAAS,CAAC;IAE1B;;;;MAIE;IACF,WAAW,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,CAAC,EAAE,MAAM,CAAC;IAEV;;;;OAIG;IACH,cAAc,CAAC,EAAG,MAAM,CAAC;IAEzB;;;;;;;;;MASE;IACF,cAAc,CAAC,EAAG,MAAM,CAAC;IAEzB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,EAAG;QACrB;;;;WAIG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B;;;;;;;;WAQG;QACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAAC;KACzD,CAAA;IAED,eAAe,CAAC,EAAG,MAAM,CAAC;CAC7B,CAAA;AAGD,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;IAClB,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,CAAC,CAAC;CACd,CAAA"}

package/dist/types/runtime.types.d.ts

@@ -0,0 +1,89 @@
+import { IsolateInstance } from "../service/Isolate.service.d.ts";
+import type { NetworkConfig } from "../network/interfaces/network.types.d.ts";
+import type { BaseEngineConfig } from "./base.types.d.ts";
+import type { PersistentEngine, SelfInvokingEngine } from "./engine.types.d.ts";
+import type { EventTriggerStrategy } from "./eventTriggerStrategry.types.d.ts";
+/**
+ * Supported runtime execution environments for Pulsar.
+ */
+export declare enum PulsarRuntime {
+    /**
+     * Configuration for ephemeral V8 isolate environments (Cloudflare Workers, Supabase Edge, Deno Deploy).
+     *
+     * In V8 isolate platforms, incoming requests share the same warm memory space until the isolate shuts down.
+     * The engine relies on the required `isolate` instance to monitor remaining isolate lifespan, handle dynamic global
+     * state, and sync tick schedules before the V8 isolate gets terminated by the cloud provider.
+     */
+    V8_ISOLATE = "v8-isolate",
+    /**
+     * Configuration for containerized or persistent runtime environments (AWS Lambda, GCP Cloud Run, Docker, Node.js VMs).
+     *
+     * Unlike V8 isolates, these environments operate in dedicated process/container sandboxes with predictable execution limits
+     * or persistent process lifetimes. Tracking V8 isolate memory and remaining uptime across HTTP invocations is not strictly required.
+     */
+    SERVERLESS_VM = "serverless-vm",
+    /**
+     * Configuration for traditional, long-running persistent environments (AWS EC2, VPS, Dedicated Servers, local Node.js processes).
+     *
+     * Unlike ephemeral isolates or serverless containers that spin down between invocations, persistent runtimes maintain an uninterrupted
+     * execution context and continuous process lifespan. The engine can rely on background event loops, stateful in-memory caching,
+     * and non-ephemeral scheduling without relying on cloud provider lifecycle hooks.
+     */
+    PERSISTENT = "persistent"
+}
+export type PulsarRuntimeType = typeof PulsarRuntime[keyof typeof PulsarRuntime];
+export type ConfigForRuntime<T extends PulsarRuntimeType> = T extends typeof PulsarRuntime.V8_ISOLATE ? V8IsolateConfig : T extends typeof PulsarRuntime.SERVERLESS_VM ? ServerlessVMConfig : PersistentConfig;
+export type V8IsolateConfig = BaseEngineConfig & {
+    runtime: typeof PulsarRuntime.V8_ISOLATE;
+    engine: SelfInvokingEngine;
+    /**
+    * Active isolate tracking instance.
+    */
+    isolate: IsolateInstance;
+};
+export type ServerlessVMConfig = BaseEngineConfig & {
+    runtime: typeof PulsarRuntime.SERVERLESS_VM;
+    engine: SelfInvokingEngine;
+    /**
+    * Optional isolate tracking instance if custom lifecycle tracking is desired inside Lambda or containerized workers.
+    */
+    isolate?: IsolateInstance;
+};
+export type PersistentConfig = BaseEngineConfig & {
+    runtime: typeof PulsarRuntime.PERSISTENT;
+    /**
+    * Optional isolate tracking instance if custom lifecycle tracking is desired inside Lambda or containerized workers.
+    */
+    isolate?: IsolateInstance;
+    networkInterface: {
+        /**
+         * Determines the operational network mode of the server.
+         *
+         * - `http`: Opens an HTTP server. Crucial for consumers running dependent workers
+         *   (e.g., when a consumer cannot initialize local storage configuration directly).
+         *   Dependent workers use this HTTP server for acks, retries, etc.
+         *   *(Note: This mode introduces latency and throughput limitations).*
+         *
+         * - `socket`: Opens a WebSocket server. Both the pulsar and consumers connect to
+         *   this socket to transport and dispatch jobs. Provides near-realtime job dispatch
+         *   performance for workers.
+         *
+         * - `hybrid`: Opens both HTTP and WebSocket servers simultaneously. Ideal for
+         *   multi-runtime deployed consumers where some instances operate in serverless
+         *   functions and others on a VPS, allowing each consumer to select its optimal
+         *   server option based on its specific configuration.
+        */
+        mode: Exclude<NetworkConfig["mode"], "client">;
+        /**
+         * The port number on which the server instance will listen for incoming traffic.
+        */
+        port: NetworkConfig["port"];
+        /**
+         * Optional hostname or IP address to bind the server to.
+        */
+        host?: NetworkConfig["host"];
+    };
+    eventTriggerStrategy: typeof EventTriggerStrategy[keyof typeof EventTriggerStrategy];
+    engine: PersistentEngine;
+};
+//# sourceMappingURL=runtime.types.d.ts.map

package/dist/types/runtime.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.types.d.ts","sourceRoot":"","sources":["../../src/types/runtime.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAE7E;;GAEG;AACH,oBAAY,aAAa;IACrB;;;;;;OAMG;IACH,UAAU,eAAe;IAEzB;;;;;OAKG;IACH,aAAa,kBAAkB;IAE/B;;;;;;OAMG;IACH,UAAU,eAAe;CAC5B;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,aAAa,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAEjF,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,iBAAiB,IACpD,CAAC,SAAS,OAAO,aAAa,CAAC,UAAU,GAAG,eAAe,GAC3D,CAAC,SAAS,OAAO,aAAa,CAAC,aAAa,GAAG,kBAAkB,GACjE,gBAAgB,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG;IAC7C,OAAO,EAAG,OAAO,aAAa,CAAC,UAAU,CAAC;IAC1C,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;MAEE;IACF,OAAO,EAAG,eAAe,CAAC;CAC7B,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG;IAChD,OAAO,EAAG,OAAO,aAAa,CAAC,aAAa,CAAC;IAC7C,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;MAEE;IACF,OAAO,CAAC,EAAG,eAAe,CAAC;CAC9B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAC9C,OAAO,EAAG,OAAO,aAAa,CAAC,UAAU,CAAC;IAE1C;;MAEE;IACF,OAAO,CAAC,EAAG,eAAe,CAAC;IAE3B,gBAAgB,EAAG;QACf;;;;;;;;;;;;;;;;UAgBE;QACF,IAAI,EAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;QAChD;;UAEE;QACF,IAAI,EAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7B;;UAEE;QACF,IAAI,CAAC,EAAG,aAAa,CAAC,MAAM,CAAC,CAAC;KACjC,CAAA;IAED,oBAAoB,EAAG,OAAO,oBAAoB,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;IACtF,MAAM,EAAG,gBAAgB,CAAC;CAC7B,CAAA"}

package/package.json

@@ -1,6 +1,73 @@
 {
-  "name": "@hamim_4444/pulsar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@hamim_4444/pulsar",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "index.ts",
+	"types": "./dist/index.d.ts",
+	"private": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./helpers": {
+			"types": "./dist/helpers/index.d.ts",
+			"import": "./dist/helpers/index.js",
+			"default": "./dist/helpers/index.js"
+		},
+		"./integrations": {
+			"types": "./dist/integrations/index.d.ts",
+			"import": "./dist/integrations/index.js",
+			"default": "./dist/integrations/index.js"
+		},
+		"./server": {
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
+		},
+		"./storage": {
+			"types": "./dist/storage/index.d.ts",
+			"import": "./dist/storage/index.js",
+			"default": "./dist/storage/index.js"
+		}
+	},
+	"typesVersions": {
+		"*": {
+			"storage": [
+				"./dist/storage/index.d.ts"
+			],
+			"server": [
+				"./dist/server/index.d.ts"
+			],
+			"integrations": [
+				"./dist/integrations/index.d.ts"
+			]
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun run build.ts; bun pm pack;",
+		"dev": "bun --preload ./lua-plugin.ts src/run/index.ts"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@hono/node-server": "^2.1.3",
+		"@upstash/redis": "^1.39.0",
+		"crossws": "^0.4.16",
+		"eventemitter3": "^5.0.4",
+		"hono": "^4.13.12",
+		"ioredis": "^6.0.0",
+		"js-sha256": "^1.0.0",
+		"postgres": "^3.4.9",
+		"srvx": "^1.0.7"
+	}
+}