@hazeljs/prompts 0.2.0-alpha.1

package/dist/stores/store.interface.d.ts

@@ -0,0 +1,62 @@
+import type { PromptMetadata } from '../types';
+/**
+ * A serializable snapshot of one version of a registered prompt.
+ * This is what gets persisted to / loaded from any store backend.
+ */
+export interface PromptEntry {
+    /** Registry key (e.g. `rag:graph:entity-extraction`). */
+    key: string;
+    /**
+     * Semantic version string (e.g. `1.0.0`).
+     * Defaults to `'latest'` when `PromptMetadata.version` is not set.
+     */
+    version: string;
+    /** Raw template string with `{variable}` placeholders. */
+    template: string;
+    /** Human-readable metadata. */
+    metadata: PromptMetadata;
+    /** ISO-8601 timestamp of when the entry was written to the store. */
+    storedAt: string;
+}
+/**
+ * PromptStore
+ *
+ * Async storage contract implemented by every backend.
+ * All methods are async so implementations can use any I/O mechanism
+ * (file system, Redis, SQL/NoSQL, HTTP, etc.) without blocking the event loop.
+ *
+ * Versioning semantics:
+ * - Every entry is stored under a `(key, version)` pair.
+ * - `version` defaults to `'latest'` when not supplied.
+ * - `get(key)` returns the `'latest'` version.
+ * - `get(key, '1.2.0')` returns a specific historical version.
+ */
+export interface PromptStore {
+    /** Human-readable identifier shown in error messages and logs. */
+    readonly name: string;
+    /**
+     * Retrieve the entry for `key` at `version` (defaults to `'latest'`).
+     * Returns `undefined` when the entry does not exist.
+     */
+    get(key: string, version?: string): Promise<PromptEntry | undefined>;
+    /**
+     * Persist `entry` to the store.
+     * If an entry with the same `(key, version)` already exists it is overwritten.
+     */
+    set(entry: PromptEntry): Promise<void>;
+    /**
+     * Remove the entry for `key` at `version`.
+     * If `version` is omitted, ALL versions of the key are removed.
+     */
+    delete(key: string, version?: string): Promise<void>;
+    /** Returns `true` when an entry for `key@version` exists. */
+    has(key: string, version?: string): Promise<boolean>;
+    /** Returns all distinct keys currently stored (deduplicated across versions). */
+    keys(): Promise<string[]>;
+    /**
+     * Returns all stored version strings for a given key in ascending semver order.
+     * Returns an empty array when the key does not exist.
+     */
+    versions(key: string): Promise<string[]>;
+}
+//# sourceMappingURL=store.interface.d.ts.map

package/dist/stores/store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.interface.d.ts","sourceRoot":"","sources":["../../src/stores/store.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAErE;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,6DAA6D;IAC7D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD,iFAAiF;IACjF,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C"}

package/dist/stores/store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=store.interface.js.map

package/dist/stores/store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.interface.js","sourceRoot":"","sources":["../../src/stores/store.interface.ts"],"names":[],"mappings":""}

package/dist/template.d.ts

@@ -0,0 +1,38 @@
+/**
+ * PromptTemplate<TVariables>
+ *
+ * A typed, reusable prompt template that interpolates named `{variable}`
+ * placeholders with caller-supplied values.
+ *
+ * Usage:
+ * ```typescript
+ * const tpl = new PromptTemplate<{ query: string; context: string }>(
+ *   'Answer the question using the context.\nContext: {context}\nQuestion: {query}',
+ *   { name: 'RAG Answer', version: '1.0.0' },
+ * );
+ *
+ * const rendered = tpl.render({ query: 'What is TypeScript?', context: '...' });
+ * ```
+ */
+import type { PromptMetadata } from './types';
+export declare class PromptTemplate<TVariables extends object = Record<string, unknown>> {
+    /** The raw template string containing `{variableName}` placeholders. */
+    readonly template: string;
+    /** Descriptive metadata — used for debugging and the registry. */
+    readonly metadata: PromptMetadata;
+    constructor(
+    /** The raw template string containing `{variableName}` placeholders. */
+    template: string, 
+    /** Descriptive metadata — used for debugging and the registry. */
+    metadata: PromptMetadata);
+    /**
+     * Render the template by substituting all `{key}` placeholders with the
+     * corresponding values from `variables`.
+     *
+     * - If a placeholder key is present in `variables` its value is `String()`-cast.
+     * - If a placeholder key is NOT present it is left as-is (e.g. `{missing}`),
+     *   making missing variables easy to spot.
+     */
+    render(variables: TVariables): string;
+}
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,cAAc,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE3E,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,cAAc;;IAHjC,wEAAwE;IAC/D,QAAQ,EAAE,MAAM;IACzB,kEAAkE;IACzD,QAAQ,EAAE,cAAc;IAGnC;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM;CAOtC"}

package/dist/template.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * PromptTemplate<TVariables>
+ *
+ * A typed, reusable prompt template that interpolates named `{variable}`
+ * placeholders with caller-supplied values.
+ *
+ * Usage:
+ * ```typescript
+ * const tpl = new PromptTemplate<{ query: string; context: string }>(
+ *   'Answer the question using the context.\nContext: {context}\nQuestion: {query}',
+ *   { name: 'RAG Answer', version: '1.0.0' },
+ * );
+ *
+ * const rendered = tpl.render({ query: 'What is TypeScript?', context: '...' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptTemplate = void 0;
+class PromptTemplate {
+    constructor(
+    /** The raw template string containing `{variableName}` placeholders. */
+    template, 
+    /** Descriptive metadata — used for debugging and the registry. */
+    metadata) {
+        this.template = template;
+        this.metadata = metadata;
+    }
+    /**
+     * Render the template by substituting all `{key}` placeholders with the
+     * corresponding values from `variables`.
+     *
+     * - If a placeholder key is present in `variables` its value is `String()`-cast.
+     * - If a placeholder key is NOT present it is left as-is (e.g. `{missing}`),
+     *   making missing variables easy to spot.
+     */
+    render(variables) {
+        const vars = variables;
+        return this.template.replace(/\{(\w+)\}/g, (match, key) => {
+            const value = vars[key];
+            return value !== undefined ? String(value) : match;
+        });
+    }
+}
+exports.PromptTemplate = PromptTemplate;
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAIH,MAAa,cAAc;IACzB;IACE,wEAAwE;IAC/D,QAAgB;IACzB,kEAAkE;IACzD,QAAwB;QAFxB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,aAAQ,GAAR,QAAQ,CAAgB;IAChC,CAAC;IAEJ;;;;;;;OAOG;IACH,MAAM,CAAC,SAAqB;QAC1B,MAAM,IAAI,GAAG,SAAoC,CAAC;QAClD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;YAChE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAvBD,wCAuBC"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Metadata attached to every PromptTemplate.
+ */
+export interface PromptMetadata {
+    /** Unique human-readable name for this prompt. */
+    name: string;
+    /** Optional short description of what this prompt does. */
+    description?: string;
+    /**
+     * Semantic version string (e.g. '1.0.0').
+     * Bump when the prompt text changes meaningfully to aid debugging.
+     */
+    version?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@hazeljs/prompts",
+  "version": "0.2.0-alpha.1",
+  "description": "Typed, overridable prompt templates for HazelJS AI, RAG, and Agent packages",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --skipLibCheck",
+    "test": "jest --coverage --passWithNoTests",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.50",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hazeljs/hazeljs.git",
+    "directory": "packages/prompts"
+  },
+  "keywords": [
+    "hazeljs",
+    "prompts",
+    "prompt-template",
+    "llm",
+    "ai",
+    "rag",
+    "agent"
+  ],
+  "author": "Muhammad Arslan <muhammad.arslan@hazeljs.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/hazeljs/hazel-js/issues"
+  },
+  "homepage": "https://hazeljs.com",
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/src/__tests__/**/*.test.ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/__tests__/**",
+      "!src/index.ts",
+      "!src/stores/index.ts",
+      "!src/stores/redis.store.ts",
+      "!src/stores/database.store.ts"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "statements": 90,
+        "branches": 80,
+        "functions": 90,
+        "lines": 90
+      }
+    }
+  },
+  "gitHead": "cbc5ee2c12ced28fd0576faf13c5f078c1e8421e"
+}