@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/redis.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+import Redis from 'ioredis';
+import { Feature } from '../feature.js';
+import type { ContainerContext } from '../../container.js';
+export declare const RedisStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    connected: z.ZodDefault<z.ZodBoolean>;
+    url: z.ZodDefault<z.ZodString>;
+    subscriberConnected: z.ZodDefault<z.ZodBoolean>;
+    subscribedChannels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lastError: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const RedisOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    url: z.ZodOptional<z.ZodString>;
+    prefix: z.ZodOptional<z.ZodString>;
+    lazyConnect: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RedisState = z.infer<typeof RedisStateSchema>;
+export type RedisOptions = z.infer<typeof RedisOptionsSchema>;
+export declare const RedisEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    message: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    subscribed: z.ZodTuple<[z.ZodString], null>;
+    unsubscribed: z.ZodTuple<[z.ZodString], null>;
+    error: z.ZodTuple<[z.ZodString], null>;
+    closed: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+type MessageHandler = (channel: string, message: string) => void;
+/**
+ * Redis feature for shared state and pub/sub communication between container instances.
+ *
+ * Wraps ioredis with a focused API for the primitives that matter most:
+ * key/value state, pub/sub messaging, and cross-instance coordination.
+ *
+ * Uses a dedicated subscriber connection for pub/sub (ioredis requirement),
+ * created lazily on first subscribe call.
+ *
+ * @example
+ * ```typescript
+ * const redis = container.feature('redis', { url: 'redis://localhost:6379' })
+ *
+ * // Shared state
+ * await redis.set('worker:status', 'active')
+ * const status = await redis.get('worker:status')
+ *
+ * // Pub/sub between instances
+ * redis.on('message', (channel, msg) => console.log(`${channel}: ${msg}`))
+ * await redis.subscribe('tasks')
+ * await redis.publish('tasks', JSON.stringify({ type: 'ping' }))
+ *
+ * // JSON helpers
+ * await redis.setJSON('config', { workers: 4, debug: true })
+ * const config = await redis.getJSON<{ workers: number }>('config')
+ * ```
+ */
+export declare class RedisFeature extends Feature<RedisState, RedisOptions> {
+    static shortcut: "features.redis";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        connected: z.ZodDefault<z.ZodBoolean>;
+        url: z.ZodDefault<z.ZodString>;
+        subscriberConnected: z.ZodDefault<z.ZodBoolean>;
+        subscribedChannels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        lastError: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        url: z.ZodOptional<z.ZodString>;
+        prefix: z.ZodOptional<z.ZodString>;
+        lazyConnect: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        message: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        subscribed: z.ZodTuple<[z.ZodString], null>;
+        unsubscribed: z.ZodTuple<[z.ZodString], null>;
+        error: z.ZodTuple<[z.ZodString], null>;
+        closed: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    private _client;
+    private _subscriber;
+    private _prefix;
+    private _messageHandlers;
+    get initialState(): RedisState;
+    constructor(options: RedisOptions, context: ContainerContext);
+    /** The underlying ioredis client for advanced operations. */
+    get client(): Redis;
+    /** The dedicated subscriber connection, if pub/sub is active. */
+    get subscriber(): Redis | null;
+    private _key;
+    /**
+     * Set a key to a string value with optional TTL.
+     *
+     * @param key - The key name
+     * @param value - The string value to store
+     * @param ttl - Optional time-to-live in seconds
+     */
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    /**
+     * Get a key's value. Returns null if the key doesn't exist.
+     *
+     * @param key - The key name
+     * @returns The stored value, or null
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Delete one or more keys.
+     *
+     * @param keys - One or more key names to delete
+     * @returns Number of keys that were deleted
+     */
+    del(...keys: string[]): Promise<number>;
+    /**
+     * Check if a key exists.
+     *
+     * @param key - The key name
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Set a key's TTL in seconds.
+     *
+     * @param key - The key name
+     * @param seconds - TTL in seconds
+     */
+    expire(key: string, seconds: number): Promise<boolean>;
+    /**
+     * Find keys matching a glob pattern (respects prefix).
+     *
+     * @param pattern - Glob pattern, e.g. "worker:*"
+     * @returns Array of matching key names (with prefix stripped)
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Store a value as JSON.
+     *
+     * @param key - The key name
+     * @param value - Any JSON-serializable value
+     * @param ttl - Optional TTL in seconds
+     */
+    setJSON(key: string, value: unknown, ttl?: number): Promise<void>;
+    /**
+     * Retrieve and parse a JSON value.
+     *
+     * @param key - The key name
+     * @returns The parsed value, or null if the key doesn't exist
+     */
+    getJSON<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set fields on a hash.
+     *
+     * @param key - The hash key
+     * @param fields - Object of field/value pairs
+     */
+    hset(key: string, fields: Record<string, string>): Promise<void>;
+    /**
+     * Get all fields from a hash.
+     *
+     * @param key - The hash key
+     * @returns Object of field/value pairs
+     */
+    hgetall(key: string): Promise<Record<string, string>>;
+    /**
+     * Get a single field from a hash.
+     *
+     * @param key - The hash key
+     * @param field - The field name
+     */
+    hget(key: string, field: string): Promise<string | null>;
+    /**
+     * Ensures the dedicated subscriber connection exists.
+     * ioredis requires a separate connection for subscriptions.
+     */
+    private _ensureSubscriber;
+    /**
+     * Subscribe to one or more channels.
+     *
+     * Optionally pass a handler that fires only for these channels.
+     * The feature also emits a `message` event for all messages.
+     *
+     * @param channels - Channel name(s) to subscribe to
+     * @param handler - Optional per-channel message handler
+     *
+     * @example
+     * ```typescript
+     * await redis.subscribe('tasks', (channel, msg) => {
+     *   console.log(`Got ${msg} on ${channel}`)
+     * })
+     * ```
+     */
+    subscribe(channels: string | string[], handler?: MessageHandler): Promise<void>;
+    /**
+     * Unsubscribe from one or more channels.
+     *
+     * @param channels - Channel name(s) to unsubscribe from
+     */
+    unsubscribe(...channels: string[]): Promise<void>;
+    /**
+     * Publish a message to a channel.
+     *
+     * @param channel - The channel to publish to
+     * @param message - The message string (use JSON.stringify for objects)
+     * @returns Number of subscribers that received the message
+     */
+    publish(channel: string, message: string): Promise<number>;
+    /**
+     * Spin up a local Redis instance via Docker. Checks if a container with
+     * the given name already exists and starts it if stopped, or creates a
+     * new one from redis:alpine.
+     *
+     * Requires the docker feature to be available on the container.
+     *
+     * @param options - Container name and host port
+     * @returns The docker container ID
+     *
+     * @example
+     * ```typescript
+     * const redis = container.feature('redis', { url: 'redis://localhost:6379', lazyConnect: true })
+     * await redis.ensureLocalDocker()
+     * ```
+     */
+    ensureLocalDocker(options?: {
+        name?: string;
+        port?: number;
+        image?: string;
+    }): Promise<string>;
+    /**
+     * Close all redis connections (main client + subscriber).
+     */
+    close(): Promise<this>;
+}
+export { RedisFeature as Redis };
+export default RedisFeature;
+declare module '../../feature.js' {
+    interface AvailableFeatures {
+        redis: typeof RedisFeature;
+    }
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/node/features/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/node/features/redis.ts"],"names":[],"mappings":"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"}

package/dist/node/features/repl.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+import vm from 'vm';
+import readline from 'readline';
+export declare const ReplStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    started: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type ReplState = z.infer<typeof ReplStateSchema>;
+export declare const ReplOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    prompt: z.ZodOptional<z.ZodString>;
+    historyPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReplOptions = z.infer<typeof ReplOptionsSchema>;
+/**
+ * REPL feature — provides an interactive read-eval-print loop with tab completion and history.
+ *
+ * Launches a REPL session that evaluates JavaScript/TypeScript expressions in a sandboxed
+ * VM context populated with the container and its helpers. Supports tab completion for
+ * dot-notation property access, command history persistence, and async/await.
+ *
+ * @example
+ * ```typescript
+ * const repl = container.feature('repl', { enable: true })
+ * await repl.start({ context: { myVar: 42 } })
+ * ```
+ */
+export declare class Repl<T extends ReplState = ReplState, K extends ReplOptions = ReplOptions> extends Feature<T, K> {
+    static shortcut: "features.repl";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        started: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        prompt: z.ZodOptional<z.ZodString>;
+        historyPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    /** Whether the REPL session is currently running. */
+    get isStarted(): boolean;
+    _rl?: readline.Interface;
+    _vmContext?: vm.Context;
+    _history: string[];
+    _historyPath?: string;
+    /** The VM context object used for evaluating expressions in the REPL. */
+    get vmContext(): vm.Context | undefined;
+    /**
+     * Start the REPL session.
+     *
+     * Creates a VM context populated with the container and its helpers, sets up
+     * readline with tab completion and history, then enters the interactive loop.
+     * Type `.exit` or `exit` to quit. Supports top-level await.
+     *
+     * @param options - Configuration for the REPL session
+     * @param options.historyPath - Custom path for the history file (defaults to ~/.cache/luca/repl-{cwdHash}.history)
+     * @param options.context - Additional variables to inject into the VM context
+     * @returns The Repl instance
+     *
+     * @example
+     * ```typescript
+     * const repl = container.feature('repl', { enable: true })
+     * await repl.start({
+     *   context: { db: myDatabase },
+     *   historyPath: '.repl-history'
+     * })
+     * ```
+     */
+    start(options?: {
+        historyPath?: string;
+        context?: any;
+    }): Promise<this>;
+    /** Open a fresh readline and enter the REPL loop using the existing VM context. */
+    private _resume;
+    private _saveHistory;
+}
+export default Repl;
+//# sourceMappingURL=repl.d.ts.map

package/dist/node/features/repl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../../src/node/features/repl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,QAAQ,MAAM,UAAU,CAAA;AAG/B,eAAO,MAAM,eAAe;;;iBAE1B,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD,eAAO,MAAM,iBAAiB;;;;;;;iBAG5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;;;;;;;;;;;GAYG;AACH,qBAAa,IAAI,CACf,CAAC,SAAS,SAAS,GAAG,SAAS,EAC/B,CAAC,SAAS,WAAW,GAAG,WAAW,CACnC,SAAQ,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACrB,OAAgB,QAAQ,EAAG,eAAe,CAAS;IACnD,OAAgB,WAAW;;;sBAAkB;IAC7C,OAAgB,aAAa;;;;;;;sBAAoB;IAGjD,qDAAqD;IACrD,IAAI,SAAS,YAEZ;IAED,GAAG,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAA;IACxB,UAAU,CAAC,EAAE,EAAE,CAAC,OAAO,CAAA;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAK;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,yEAAyE;IACzE,IAAI,SAAS,2BAEZ;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CAAC,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAO;IA6CjE,mFAAmF;IACnF,OAAO,CAAC,OAAO;IAiFf,OAAO,CAAC,YAAY;CAMrB;AAED,eAAe,IAAI,CAAA"}