@utilarium/overcontext 0.0.4-dev.0

package/dist/schema/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sources":["../../src/schema/validation.ts"],"sourcesContent":["import { z, ZodError } from 'zod';\nimport { BaseEntity, BaseEntitySchema } from './base';\n\nexport interface ValidationResult<T> {\n    success: boolean;\n    data?: T;\n    errors?: Array<{ path: string; message: string }>;\n}\n\n/**\n * Validate that an object satisfies at least the base entity contract.\n */\nexport const validateBaseEntity = (data: unknown): ValidationResult<BaseEntity> => {\n    const result = BaseEntitySchema.safeParse(data);\n\n    if (result.success) {\n        return { success: true, data: result.data };\n    }\n\n    return {\n        success: false,\n        errors: result.error.issues.map(e => ({\n            path: e.path.join('.'),\n            message: e.message,\n        })),\n    };\n};\n\n/**\n * Validate data against a specific schema.\n */\nexport const validateEntity = <T extends BaseEntity>(\n    schema: z.ZodType<T>,\n    data: unknown\n): ValidationResult<T> => {\n    const result = schema.safeParse(data);\n\n    if (result.success) {\n        return { success: true, data: result.data };\n    }\n\n    return {\n        success: false,\n        errors: result.error.issues.map(e => ({\n            path: e.path.join('.'),\n            message: e.message,\n        })),\n    };\n};\n\n/**\n * Check if data extends the base entity (has id, name, type).\n */\nexport const isBaseEntity = (data: unknown): data is BaseEntity => {\n    return validateBaseEntity(data).success;\n};\n\n/**\n * Format Zod errors into a readable message.\n */\nexport const formatValidationErrors = (errors: ZodError): string => {\n    return errors.issues\n        .map(e => `${e.path.join('.')}: ${e.message}`)\n        .join('; ');\n};\n"],"names":["validateBaseEntity","data","result","BaseEntitySchema","safeParse","success","errors","error","issues","map","e","path","join","message","validateEntity","schema","isBaseEntity","formatValidationErrors"],"mappings":";;AASA;;IAGO,MAAMA,kBAAAA,GAAqB,CAACC,IAAAA,GAAAA;IAC/B,MAAMC,MAAAA,GAASC,gBAAAA,CAAiBC,SAAS,CAACH,IAAAA,CAAAA;IAE1C,IAAIC,MAAAA,CAAOG,OAAO,EAAE;QAChB,OAAO;YAAEA,OAAAA,EAAS,IAAA;AAAMJ,YAAAA,IAAAA,EAAMC,OAAOD;AAAK,SAAA;AAC9C,IAAA;IAEA,OAAO;QACHI,OAAAA,EAAS,KAAA;QACTC,MAAAA,EAAQJ,MAAAA,CAAOK,KAAK,CAACC,MAAM,CAACC,GAAG,CAACC,CAAAA,CAAAA,IAAM;AAClCC,gBAAAA,IAAAA,EAAMD,CAAAA,CAAEC,IAAI,CAACC,IAAI,CAAC,GAAA,CAAA;AAClBC,gBAAAA,OAAAA,EAASH,EAAEG;aACf,CAAA;AACJ,KAAA;AACJ;AAEA;;AAEC,IACM,MAAMC,cAAAA,GAAiB,CAC1BC,MAAAA,EACAd,IAAAA,GAAAA;IAEA,MAAMC,MAAAA,GAASa,MAAAA,CAAOX,SAAS,CAACH,IAAAA,CAAAA;IAEhC,IAAIC,MAAAA,CAAOG,OAAO,EAAE;QAChB,OAAO;YAAEA,OAAAA,EAAS,IAAA;AAAMJ,YAAAA,IAAAA,EAAMC,OAAOD;AAAK,SAAA;AAC9C,IAAA;IAEA,OAAO;QACHI,OAAAA,EAAS,KAAA;QACTC,MAAAA,EAAQJ,MAAAA,CAAOK,KAAK,CAACC,MAAM,CAACC,GAAG,CAACC,CAAAA,CAAAA,IAAM;AAClCC,gBAAAA,IAAAA,EAAMD,CAAAA,CAAEC,IAAI,CAACC,IAAI,CAAC,GAAA,CAAA;AAClBC,gBAAAA,OAAAA,EAASH,EAAEG;aACf,CAAA;AACJ,KAAA;AACJ;AAEA;;IAGO,MAAMG,YAAAA,GAAe,CAACf,IAAAA,GAAAA;IACzB,OAAOD,kBAAAA,CAAmBC,MAAMI,OAAO;AAC3C;AAEA;;IAGO,MAAMY,sBAAAA,GAAyB,CAACX,MAAAA,GAAAA;IACnC,OAAOA,MAAAA,CAAOE,MAAM,CACfC,GAAG,CAACC,CAAAA,CAAAA,GAAK,GAAGA,CAAAA,CAAEC,IAAI,CAACC,IAAI,CAAC,KAAK,EAAE,EAAEF,EAAEG,OAAO,CAAA,CAAE,CAAA,CAC5CD,IAAI,CAAC,IAAA,CAAA;AACd;;;;"}

package/dist/storage/errors.d.ts

@@ -0,0 +1,35 @@
+export declare class StorageError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+export declare class EntityNotFoundError extends StorageError {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly namespace?: string | undefined;
+    constructor(entityType: string, entityId: string, namespace?: string | undefined);
+}
+export declare class SchemaNotRegisteredError extends StorageError {
+    readonly entityType: string;
+    constructor(entityType: string);
+}
+export declare class ValidationError extends StorageError {
+    readonly validationErrors: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(message: string, validationErrors: Array<{
+        path: string;
+        message: string;
+    }>);
+}
+export declare class StorageAccessError extends StorageError {
+    constructor(message: string, cause?: Error);
+}
+export declare class ReadonlyStorageError extends StorageError {
+    constructor();
+}
+export declare class NamespaceNotFoundError extends StorageError {
+    readonly namespace: string;
+    constructor(namespace: string);
+}

package/dist/storage/errors.js

@@ -0,0 +1,58 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class StorageError extends Error {
+    constructor(message, code, cause){
+        super(message), _define_property(this, "code", void 0), _define_property(this, "cause", void 0), this.code = code, this.cause = cause;
+        this.name = 'StorageError';
+    }
+}
+class EntityNotFoundError extends StorageError {
+    constructor(entityType, entityId, namespace){
+        super(`Entity not found: ${entityType}/${entityId}${namespace ? ` in ${namespace}` : ''}`, 'ENTITY_NOT_FOUND'), _define_property(this, "entityType", void 0), _define_property(this, "entityId", void 0), _define_property(this, "namespace", void 0), this.entityType = entityType, this.entityId = entityId, this.namespace = namespace;
+        this.name = 'EntityNotFoundError';
+    }
+}
+class SchemaNotRegisteredError extends StorageError {
+    constructor(entityType){
+        super(`Schema not registered for type: ${entityType}`, 'SCHEMA_NOT_REGISTERED'), _define_property(this, "entityType", void 0), this.entityType = entityType;
+        this.name = 'SchemaNotRegisteredError';
+    }
+}
+class ValidationError extends StorageError {
+    constructor(message, validationErrors){
+        super(message, 'VALIDATION_ERROR'), _define_property(this, "validationErrors", void 0), this.validationErrors = validationErrors;
+        this.name = 'ValidationError';
+    }
+}
+class StorageAccessError extends StorageError {
+    constructor(message, cause){
+        super(message, 'STORAGE_ACCESS_ERROR', cause);
+        this.name = 'StorageAccessError';
+    }
+}
+class ReadonlyStorageError extends StorageError {
+    constructor(){
+        super('Storage is readonly', 'READONLY_STORAGE');
+        this.name = 'ReadonlyStorageError';
+    }
+}
+class NamespaceNotFoundError extends StorageError {
+    constructor(namespace){
+        super(`Namespace not found: ${namespace}`, 'NAMESPACE_NOT_FOUND'), _define_property(this, "namespace", void 0), this.namespace = namespace;
+        this.name = 'NamespaceNotFoundError';
+    }
+}
+
+export { EntityNotFoundError, NamespaceNotFoundError, ReadonlyStorageError, SchemaNotRegisteredError, StorageAccessError, StorageError, ValidationError };
+//# sourceMappingURL=errors.js.map

package/dist/storage/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sources":["../../src/storage/errors.ts"],"sourcesContent":["export class StorageError extends Error {\n    constructor(\n        message: string,\n        public readonly code: string,\n        public readonly cause?: Error\n    ) {\n        super(message);\n        this.name = 'StorageError';\n    }\n}\n\nexport class EntityNotFoundError extends StorageError {\n    constructor(\n        public readonly entityType: string,\n        public readonly entityId: string,\n        public readonly namespace?: string\n    ) {\n        super(\n            `Entity not found: ${entityType}/${entityId}${namespace ? ` in ${namespace}` : ''}`,\n            'ENTITY_NOT_FOUND'\n        );\n        this.name = 'EntityNotFoundError';\n    }\n}\n\nexport class SchemaNotRegisteredError extends StorageError {\n    constructor(public readonly entityType: string) {\n        super(\n            `Schema not registered for type: ${entityType}`,\n            'SCHEMA_NOT_REGISTERED'\n        );\n        this.name = 'SchemaNotRegisteredError';\n    }\n}\n\nexport class ValidationError extends StorageError {\n    constructor(\n        message: string,\n        public readonly validationErrors: Array<{ path: string; message: string }>\n    ) {\n        super(message, 'VALIDATION_ERROR');\n        this.name = 'ValidationError';\n    }\n}\n\nexport class StorageAccessError extends StorageError {\n    constructor(message: string, cause?: Error) {\n        super(message, 'STORAGE_ACCESS_ERROR', cause);\n        this.name = 'StorageAccessError';\n    }\n}\n\nexport class ReadonlyStorageError extends StorageError {\n    constructor() {\n        super('Storage is readonly', 'READONLY_STORAGE');\n        this.name = 'ReadonlyStorageError';\n    }\n}\n\nexport class NamespaceNotFoundError extends StorageError {\n    constructor(public readonly namespace: string) {\n        super(`Namespace not found: ${namespace}`, 'NAMESPACE_NOT_FOUND');\n        this.name = 'NamespaceNotFoundError';\n    }\n}\n"],"names":["StorageError","Error","message","code","cause","name","EntityNotFoundError","entityType","entityId","namespace","SchemaNotRegisteredError","ValidationError","validationErrors","StorageAccessError","ReadonlyStorageError","NamespaceNotFoundError"],"mappings":";;;;;;;;;;;;;AAAO,MAAMA,YAAAA,SAAqBC,KAAAA,CAAAA;AAC9B,IAAA,WAAA,CACIC,OAAe,EACCC,IAAY,EACZC,KAAa,CAC/B;AACE,QAAA,KAAK,CAACF,OAAAA,CAAAA,EAAAA,gBAAAA,CAAAA,IAAAA,EAAAA,MAAAA,EAAAA,MAAAA,CAAAA,EAAAA,gBAAAA,CAAAA,IAAAA,EAAAA,OAAAA,EAAAA,MAAAA,CAAAA,EAAAA,IAAAA,CAHUC,IAAAA,GAAAA,IAAAA,EAAAA,IAAAA,CACAC,KAAAA,GAAAA,KAAAA;QAGhB,IAAI,CAACC,IAAI,GAAG,cAAA;AAChB,IAAA;AACJ;AAEO,MAAMC,mBAAAA,SAA4BN,YAAAA,CAAAA;IACrC,WAAA,CACoBO,UAAkB,EAClBC,QAAgB,EAChBC,SAAkB,CACpC;QACE,KAAK,CACD,CAAC,kBAAkB,EAAEF,WAAW,CAAC,EAAEC,WAAWC,SAAAA,GAAY,CAAC,IAAI,EAAEA,SAAAA,CAAAA,CAAW,GAAG,EAAA,CAAA,CAAI,EACnF,iKANYF,UAAAA,GAAAA,UAAAA,EAAAA,IAAAA,CACAC,QAAAA,GAAAA,QAAAA,EAAAA,IAAAA,CACAC,SAAAA,GAAAA,SAAAA;QAMhB,IAAI,CAACJ,IAAI,GAAG,qBAAA;AAChB,IAAA;AACJ;AAEO,MAAMK,wBAAAA,SAAiCV,YAAAA,CAAAA;IAC1C,WAAA,CAA4BO,UAAkB,CAAE;AAC5C,QAAA,KAAK,CACD,CAAC,gCAAgC,EAAEA,UAAAA,CAAAA,CAAY,EAC/C,6EAHoBA,UAAAA,GAAAA,UAAAA;QAKxB,IAAI,CAACF,IAAI,GAAG,0BAAA;AAChB,IAAA;AACJ;AAEO,MAAMM,eAAAA,SAAwBX,YAAAA,CAAAA;AACjC,IAAA,WAAA,CACIE,OAAe,EACf,gBAA0E,CAC5E;QACE,KAAK,CAACA,OAAAA,EAAS,kBAAA,CAAA,EAAA,gBAAA,CAAA,IAAA,EAAA,kBAAA,EAAA,MAAA,CAAA,EAAA,IAAA,CAFCU,gBAAAA,GAAAA,gBAAAA;QAGhB,IAAI,CAACP,IAAI,GAAG,iBAAA;AAChB,IAAA;AACJ;AAEO,MAAMQ,kBAAAA,SAA2Bb,YAAAA,CAAAA;IACpC,WAAA,CAAYE,OAAe,EAAEE,KAAa,CAAE;QACxC,KAAK,CAACF,SAAS,sBAAA,EAAwBE,KAAAA,CAAAA;QACvC,IAAI,CAACC,IAAI,GAAG,oBAAA;AAChB,IAAA;AACJ;AAEO,MAAMS,oBAAAA,SAA6Bd,YAAAA,CAAAA;IACtC,WAAA,EAAc;AACV,QAAA,KAAK,CAAC,qBAAA,EAAuB,kBAAA,CAAA;QAC7B,IAAI,CAACK,IAAI,GAAG,sBAAA;AAChB,IAAA;AACJ;AAEO,MAAMU,sBAAAA,SAA+Bf,YAAAA,CAAAA;IACxC,WAAA,CAA4BS,SAAiB,CAAE;AAC3C,QAAA,KAAK,CAAC,CAAC,qBAAqB,EAAEA,SAAAA,CAAAA,CAAW,EAAE,0EADnBA,SAAAA,GAAAA,SAAAA;QAExB,IAAI,CAACJ,IAAI,GAAG,wBAAA;AAChB,IAAA;AACJ;;;;"}

package/dist/storage/events.d.ts

@@ -0,0 +1,50 @@
+import { BaseEntity } from '../schema/base';
+import { StorageProvider } from './interface';
+export type StorageEventType = 'entity:created' | 'entity:updated' | 'entity:deleted' | 'batch:saved' | 'batch:deleted' | 'storage:initialized' | 'storage:disposed';
+export interface StorageEvent {
+    type: StorageEventType;
+    timestamp: Date;
+    namespace?: string;
+}
+export interface EntityCreatedEvent extends StorageEvent {
+    type: 'entity:created';
+    entityType: string;
+    entityId: string;
+    entity: BaseEntity;
+}
+export interface EntityUpdatedEvent extends StorageEvent {
+    type: 'entity:updated';
+    entityType: string;
+    entityId: string;
+    entity: BaseEntity;
+    previousEntity?: BaseEntity;
+}
+export interface EntityDeletedEvent extends StorageEvent {
+    type: 'entity:deleted';
+    entityType: string;
+    entityId: string;
+}
+export interface BatchSavedEvent extends StorageEvent {
+    type: 'batch:saved';
+    entities: BaseEntity[];
+}
+export interface BatchDeletedEvent extends StorageEvent {
+    type: 'batch:deleted';
+    refs: Array<{
+        type: string;
+        id: string;
+    }>;
+    deletedCount: number;
+}
+export type AnyStorageEvent = EntityCreatedEvent | EntityUpdatedEvent | EntityDeletedEvent | BatchSavedEvent | BatchDeletedEvent | StorageEvent;
+export type StorageEventHandler = (event: AnyStorageEvent) => void;
+/**
+ * Observable storage provider with event subscription.
+ */
+export interface ObservableStorageProvider extends StorageProvider {
+    /**
+     * Subscribe to storage events.
+     * Returns unsubscribe function.
+     */
+    subscribe(handler: StorageEventHandler): () => void;
+}

package/dist/storage/filesystem.d.ts

@@ -0,0 +1,10 @@
+import { StorageProvider, StorageProviderOptions } from './interface';
+export interface FileSystemProviderOptions extends StorageProviderOptions {
+    /** Base path for context storage */
+    basePath: string;
+    /** Create directories if they don't exist */
+    createIfMissing?: boolean;
+    /** File extension to use (default: .yaml) */
+    extension?: '.yaml' | '.yml';
+}
+export declare const createFileSystemProvider: (options: FileSystemProviderOptions) => Promise<StorageProvider>;

package/dist/storage/filesystem.js

@@ -0,0 +1,284 @@
+import * as fs from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+import { ReadonlyStorageError, SchemaNotRegisteredError, StorageAccessError, ValidationError } from './errors.js';
+
+const createFileSystemProvider = async (options)=>{
+    const { basePath, registry, createIfMissing = true, extension = '.yaml', readonly = false, defaultNamespace } = options;
+    // --- Helper Functions ---
+    const getEntityDir = (type, namespace)=>{
+        const dirName = registry.getDirectoryName(type);
+        if (!dirName) {
+            throw new SchemaNotRegisteredError(type);
+        }
+        if (namespace) {
+            return path.join(basePath, namespace, dirName);
+        }
+        return path.join(basePath, dirName);
+    };
+    const getEntityPath = (type, id, namespace)=>{
+        return path.join(getEntityDir(type, namespace), `${id}${extension}`);
+    };
+    const ensureDir = async (dir)=>{
+        if (!existsSync(dir) && createIfMissing && !readonly) {
+            await fs.mkdir(dir, {
+                recursive: true
+            });
+        }
+    };
+    const readEntity = async (filePath, type)=>{
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            let parsed;
+            try {
+                parsed = yaml.load(content);
+            } catch (yamlError) {
+                // eslint-disable-next-line no-console
+                console.warn(`Invalid YAML at ${filePath}:`, yamlError);
+                return undefined;
+            }
+            if (!parsed || typeof parsed !== 'object') {
+                return undefined;
+            }
+            // Validate against registered schema
+            const result = registry.validateAs(type, {
+                ...parsed,
+                source: filePath
+            });
+            if (!result.success) {
+                // eslint-disable-next-line no-console
+                console.warn(`Invalid entity at ${filePath}:`, result.errors);
+                return undefined;
+            }
+            return result.data;
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw new StorageAccessError(`Failed to read ${filePath}`, error);
+        }
+    };
+    const writeEntity = async (entity, namespace)=>{
+        if (readonly) {
+            throw new ReadonlyStorageError();
+        }
+        // Validate against schema
+        const validationResult = registry.validate(entity);
+        if (!validationResult.success) {
+            throw new ValidationError('Entity validation failed', validationResult.errors || []);
+        }
+        const dir = getEntityDir(entity.type, namespace);
+        await ensureDir(dir);
+        const filePath = getEntityPath(entity.type, entity.id, namespace);
+        // Remove framework-managed fields from saved YAML
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { type: _type, source: _source, ...entityToSave } = entity;
+        // Update metadata
+        const now = new Date();
+        const toSave = {
+            ...entityToSave,
+            updatedAt: now,
+            createdAt: entityToSave.createdAt || now
+        };
+        const content = yaml.dump(toSave, {
+            lineWidth: -1,
+            sortKeys: false
+        });
+        await fs.writeFile(filePath, content, 'utf-8');
+        return {
+            ...entity,
+            ...toSave,
+            type: entity.type,
+            source: filePath
+        };
+    };
+    const listDirectoryTypes = async (basePath)=>{
+        const types = [];
+        try {
+            const entries = await fs.readdir(basePath, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                if (entry.isDirectory()) {
+                    const type = registry.getTypeFromDirectory(entry.name);
+                    if (type) {
+                        types.push(type);
+                    }
+                }
+            }
+        } catch  {
+        // Directory doesn't exist
+        }
+        return types;
+    };
+    // --- StorageProvider Implementation ---
+    const provider = {
+        name: 'filesystem',
+        location: basePath,
+        registry,
+        async initialize () {
+            if (createIfMissing && !readonly) {
+                await ensureDir(basePath);
+            }
+            if (!existsSync(basePath)) {
+                throw new StorageAccessError(`Context path does not exist: ${basePath}`);
+            }
+        },
+        async dispose () {
+        // No cleanup needed for filesystem
+        },
+        async isAvailable () {
+            try {
+                const stat = statSync(basePath);
+                return stat.isDirectory();
+            } catch  {
+                return false;
+            }
+        },
+        async get (type, id, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            const filePath = getEntityPath(type, id, ns);
+            return readEntity(filePath, type);
+        },
+        async getAll (type, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            let dir;
+            try {
+                dir = getEntityDir(type, ns);
+            } catch (error) {
+                if (error instanceof SchemaNotRegisteredError) {
+                    return [];
+                }
+                throw error;
+            }
+            if (!existsSync(dir)) {
+                return [];
+            }
+            const files = await fs.readdir(dir);
+            const entities = [];
+            for (const file of files){
+                if (!file.endsWith('.yaml') && !file.endsWith('.yml')) {
+                    continue;
+                }
+                const entity = await readEntity(path.join(dir, file), type);
+                if (entity) {
+                    entities.push(entity);
+                }
+            }
+            return entities;
+        },
+        async find (filter) {
+            var _filter_namespace;
+            var _filter_ids;
+            let results = [];
+            const types = filter.type ? Array.isArray(filter.type) ? filter.type : [
+                filter.type
+            ] : registry.types();
+            const namespace = (_filter_namespace = filter.namespace) !== null && _filter_namespace !== void 0 ? _filter_namespace : defaultNamespace;
+            for (const type of types){
+                const entities = await this.getAll(type, namespace);
+                results = results.concat(entities);
+            }
+            // Apply ID filter
+            if ((_filter_ids = filter.ids) === null || _filter_ids === void 0 ? void 0 : _filter_ids.length) {
+                results = results.filter((e)=>filter.ids.includes(e.id));
+            }
+            // Apply search filter
+            if (filter.search) {
+                const searchLower = filter.search.toLowerCase();
+                results = results.filter((e)=>e.name.toLowerCase().includes(searchLower));
+            }
+            // Apply pagination
+            if (filter.offset) {
+                results = results.slice(filter.offset);
+            }
+            if (filter.limit) {
+                results = results.slice(0, filter.limit);
+            }
+            return results;
+        },
+        async exists (type, id, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            try {
+                const filePath = getEntityPath(type, id, ns);
+                return existsSync(filePath);
+            } catch  {
+                return false;
+            }
+        },
+        async count (filter) {
+            const results = await this.find(filter);
+            return results.length;
+        },
+        async save (entity, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            return writeEntity(entity, ns);
+        },
+        async delete (type, id, namespace) {
+            if (readonly) {
+                throw new ReadonlyStorageError();
+            }
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            try {
+                const filePath = getEntityPath(type, id, ns);
+                await fs.unlink(filePath);
+                return true;
+            } catch (error) {
+                if (error.code === 'ENOENT') {
+                    return false;
+                }
+                throw error;
+            }
+        },
+        async saveBatch (entities, namespace) {
+            const saved = [];
+            for (const entity of entities){
+                saved.push(await this.save(entity, namespace));
+            }
+            return saved;
+        },
+        async deleteBatch (refs, namespace) {
+            let count = 0;
+            for (const ref of refs){
+                if (await this.delete(ref.type, ref.id, namespace)) {
+                    count++;
+                }
+            }
+            return count;
+        },
+        async listNamespaces () {
+            const namespaces = [];
+            if (!existsSync(basePath)) {
+                return namespaces;
+            }
+            const entries = await fs.readdir(basePath, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                if (!entry.isDirectory()) continue;
+                // Check if it's a namespace (contains entity type directories)
+                // vs being an entity type directory itself
+                const subPath = path.join(basePath, entry.name);
+                const subTypes = await listDirectoryTypes(subPath);
+                if (subTypes.length > 0) {
+                    namespaces.push(entry.name);
+                }
+            }
+            return namespaces;
+        },
+        async namespaceExists (namespace) {
+            const namespacePath = path.join(basePath, namespace);
+            return existsSync(namespacePath);
+        },
+        async listTypes (namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            const searchPath = ns ? path.join(basePath, ns) : basePath;
+            return listDirectoryTypes(searchPath);
+        }
+    };
+    return provider;
+};
+
+export { createFileSystemProvider };
+//# sourceMappingURL=filesystem.js.map

package/dist/storage/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sources":["../../src/storage/filesystem.ts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport { existsSync, statSync } from 'node:fs';\nimport * as path from 'node:path';\nimport * as yaml from 'js-yaml';\nimport {\n    StorageProvider,\n    StorageProviderOptions,\n    EntityFilter,\n} from './interface';\nimport { BaseEntity } from '../schema/base';\nimport {\n    StorageAccessError,\n    ValidationError,\n    SchemaNotRegisteredError,\n    ReadonlyStorageError,\n} from './errors';\n\nexport interface FileSystemProviderOptions extends StorageProviderOptions {\n    /** Base path for context storage */\n    basePath: string;\n\n    /** Create directories if they don't exist */\n    createIfMissing?: boolean;\n\n    /** File extension to use (default: .yaml) */\n    extension?: '.yaml' | '.yml';\n}\n\nexport const createFileSystemProvider = async (\n    options: FileSystemProviderOptions\n): Promise<StorageProvider> => {\n    const {\n        basePath,\n        registry,\n        createIfMissing = true,\n        extension = '.yaml',\n        readonly = false,\n        defaultNamespace,\n    } = options;\n\n    // --- Helper Functions ---\n\n    const getEntityDir = (type: string, namespace?: string): string => {\n        const dirName = registry.getDirectoryName(type);\n        if (!dirName) {\n            throw new SchemaNotRegisteredError(type);\n        }\n\n        if (namespace) {\n            return path.join(basePath, namespace, dirName);\n        }\n        return path.join(basePath, dirName);\n    };\n\n    const getEntityPath = (type: string, id: string, namespace?: string): string => {\n        return path.join(getEntityDir(type, namespace), `${id}${extension}`);\n    };\n\n    const ensureDir = async (dir: string): Promise<void> => {\n        if (!existsSync(dir) && createIfMissing && !readonly) {\n            await fs.mkdir(dir, { recursive: true });\n        }\n    };\n\n    const readEntity = async <T extends BaseEntity>(\n        filePath: string,\n        type: string\n    ): Promise<T | undefined> => {\n        try {\n            const content = await fs.readFile(filePath, 'utf-8');\n            \n            let parsed: unknown;\n            try {\n                parsed = yaml.load(content);\n            } catch (yamlError) {\n                // eslint-disable-next-line no-console\n                console.warn(`Invalid YAML at ${filePath}:`, yamlError);\n                return undefined;\n            }\n\n            if (!parsed || typeof parsed !== 'object') {\n                return undefined;\n            }\n\n            // Validate against registered schema\n            const result = registry.validateAs<T>(type, {\n                ...(parsed as Record<string, unknown>),\n                source: filePath,\n            });\n\n            if (!result.success) {\n                // eslint-disable-next-line no-console\n                console.warn(`Invalid entity at ${filePath}:`, result.errors);\n                return undefined;\n            }\n\n            return result.data;\n        } catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return undefined;\n            }\n            throw new StorageAccessError(`Failed to read ${filePath}`, error as Error);\n        }\n    };\n\n    const writeEntity = async <T extends BaseEntity>(\n        entity: T,\n        namespace?: string\n    ): Promise<T> => {\n        if (readonly) {\n            throw new ReadonlyStorageError();\n        }\n\n        // Validate against schema\n        const validationResult = registry.validate(entity);\n        if (!validationResult.success) {\n            throw new ValidationError(\n                'Entity validation failed',\n                validationResult.errors || []\n            );\n        }\n\n        const dir = getEntityDir(entity.type, namespace);\n        await ensureDir(dir);\n\n        const filePath = getEntityPath(entity.type, entity.id, namespace);\n\n        // Remove framework-managed fields from saved YAML\n        // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        const { type: _type, source: _source, ...entityToSave } = entity;\n\n        // Update metadata\n        const now = new Date();\n        const toSave = {\n            ...entityToSave,\n            updatedAt: now,\n            createdAt: entityToSave.createdAt || now,\n        };\n\n        const content = yaml.dump(toSave, {\n            lineWidth: -1,\n            sortKeys: false,\n        });\n        await fs.writeFile(filePath, content, 'utf-8');\n\n        return {\n            ...entity,\n            ...toSave,\n            type: entity.type,\n            source: filePath,\n        } as T;\n    };\n\n    const listDirectoryTypes = async (basePath: string): Promise<string[]> => {\n        const types: string[] = [];\n\n        try {\n            const entries = await fs.readdir(basePath, { withFileTypes: true });\n\n            for (const entry of entries) {\n                if (entry.isDirectory()) {\n                    const type = registry.getTypeFromDirectory(entry.name);\n                    if (type) {\n                        types.push(type);\n                    }\n                }\n            }\n        } catch {\n            // Directory doesn't exist\n        }\n\n        return types;\n    };\n\n    // --- StorageProvider Implementation ---\n\n    const provider: StorageProvider = {\n        name: 'filesystem',\n        location: basePath,\n        registry,\n\n        async initialize(): Promise<void> {\n            if (createIfMissing && !readonly) {\n                await ensureDir(basePath);\n            }\n\n            if (!existsSync(basePath)) {\n                throw new StorageAccessError(`Context path does not exist: ${basePath}`);\n            }\n        },\n\n        async dispose(): Promise<void> {\n            // No cleanup needed for filesystem\n        },\n\n        async isAvailable(): Promise<boolean> {\n            try {\n                const stat = statSync(basePath);\n                return stat.isDirectory();\n            } catch {\n                return false;\n            }\n        },\n\n        async get<T extends BaseEntity>(\n            type: string,\n            id: string,\n            namespace?: string\n        ): Promise<T | undefined> {\n            const ns = namespace ?? defaultNamespace;\n            const filePath = getEntityPath(type, id, ns);\n            return readEntity<T>(filePath, type);\n        },\n\n        async getAll<T extends BaseEntity>(\n            type: string,\n            namespace?: string\n        ): Promise<T[]> {\n            const ns = namespace ?? defaultNamespace;\n\n            let dir: string;\n            try {\n                dir = getEntityDir(type, ns);\n            } catch (error) {\n                if (error instanceof SchemaNotRegisteredError) {\n                    return [];\n                }\n                throw error;\n            }\n\n            if (!existsSync(dir)) {\n                return [];\n            }\n\n            const files = await fs.readdir(dir);\n            const entities: T[] = [];\n\n            for (const file of files) {\n                if (!file.endsWith('.yaml') && !file.endsWith('.yml')) {\n                    continue;\n                }\n\n                const entity = await readEntity<T>(path.join(dir, file), type);\n                if (entity) {\n                    entities.push(entity);\n                }\n            }\n\n            return entities;\n        },\n\n        async find<T extends BaseEntity>(filter: EntityFilter): Promise<T[]> {\n            let results: T[] = [];\n\n            const types = filter.type\n                ? (Array.isArray(filter.type) ? filter.type : [filter.type])\n                : registry.types();\n\n            const namespace = filter.namespace ?? defaultNamespace;\n\n            for (const type of types) {\n                const entities = await this.getAll<T>(type, namespace);\n                results = results.concat(entities);\n            }\n\n            // Apply ID filter\n            if (filter.ids?.length) {\n                results = results.filter(e => filter.ids!.includes(e.id));\n            }\n\n            // Apply search filter\n            if (filter.search) {\n                const searchLower = filter.search.toLowerCase();\n                results = results.filter(e =>\n                    e.name.toLowerCase().includes(searchLower)\n                );\n            }\n\n            // Apply pagination\n            if (filter.offset) {\n                results = results.slice(filter.offset);\n            }\n            if (filter.limit) {\n                results = results.slice(0, filter.limit);\n            }\n\n            return results;\n        },\n\n        async exists(type: string, id: string, namespace?: string): Promise<boolean> {\n            const ns = namespace ?? defaultNamespace;\n            try {\n                const filePath = getEntityPath(type, id, ns);\n                return existsSync(filePath);\n            } catch {\n                return false;\n            }\n        },\n\n        async count(filter: EntityFilter): Promise<number> {\n            const results = await this.find(filter);\n            return results.length;\n        },\n\n        async save<T extends BaseEntity>(entity: T, namespace?: string): Promise<T> {\n            const ns = namespace ?? defaultNamespace;\n            return writeEntity(entity, ns);\n        },\n\n        async delete(type: string, id: string, namespace?: string): Promise<boolean> {\n            if (readonly) {\n                throw new ReadonlyStorageError();\n            }\n\n            const ns = namespace ?? defaultNamespace;\n\n            try {\n                const filePath = getEntityPath(type, id, ns);\n                await fs.unlink(filePath);\n                return true;\n            } catch (error) {\n                if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                    return false;\n                }\n                throw error;\n            }\n        },\n\n        async saveBatch<T extends BaseEntity>(\n            entities: T[],\n            namespace?: string\n        ): Promise<T[]> {\n            const saved: T[] = [];\n            for (const entity of entities) {\n                saved.push(await this.save(entity, namespace));\n            }\n            return saved;\n        },\n\n        async deleteBatch(\n            refs: Array<{ type: string; id: string }>,\n            namespace?: string\n        ): Promise<number> {\n            let count = 0;\n            for (const ref of refs) {\n                if (await this.delete(ref.type, ref.id, namespace)) {\n                    count++;\n                }\n            }\n            return count;\n        },\n\n        async listNamespaces(): Promise<string[]> {\n            const namespaces: string[] = [];\n\n            if (!existsSync(basePath)) {\n                return namespaces;\n            }\n\n            const entries = await fs.readdir(basePath, { withFileTypes: true });\n\n            for (const entry of entries) {\n                if (!entry.isDirectory()) continue;\n\n                // Check if it's a namespace (contains entity type directories)\n                // vs being an entity type directory itself\n                const subPath = path.join(basePath, entry.name);\n                const subTypes = await listDirectoryTypes(subPath);\n\n                if (subTypes.length > 0) {\n                    namespaces.push(entry.name);\n                }\n            }\n\n            return namespaces;\n        },\n\n        async namespaceExists(namespace: string): Promise<boolean> {\n            const namespacePath = path.join(basePath, namespace);\n            return existsSync(namespacePath);\n        },\n\n        async listTypes(namespace?: string): Promise<string[]> {\n            const ns = namespace ?? defaultNamespace;\n            const searchPath = ns ? path.join(basePath, ns) : basePath;\n            return listDirectoryTypes(searchPath);\n        },\n    };\n\n    return provider;\n};\n"],"names":["createFileSystemProvider","options","basePath","registry","createIfMissing","extension","readonly","defaultNamespace","getEntityDir","type","namespace","dirName","getDirectoryName","SchemaNotRegisteredError","path","join","getEntityPath","id","ensureDir","dir","existsSync","fs","mkdir","recursive","readEntity","filePath","content","readFile","parsed","yaml","load","yamlError","console","warn","undefined","result","validateAs","source","success","errors","data","error","code","StorageAccessError","writeEntity","entity","ReadonlyStorageError","validationResult","validate","ValidationError","_type","_source","entityToSave","now","Date","toSave","updatedAt","createdAt","dump","lineWidth","sortKeys","writeFile","listDirectoryTypes","types","entries","readdir","withFileTypes","entry","isDirectory","getTypeFromDirectory","name","push","provider","location","initialize","dispose","isAvailable","stat","statSync","get","ns","getAll","files","entities","file","endsWith","find","filter","results","Array","isArray","concat","ids","length","e","includes","search","searchLower","toLowerCase","offset","slice","limit","exists","count","save","delete","unlink","saveBatch","saved","deleteBatch","refs","ref","listNamespaces","namespaces","subPath","subTypes","namespaceExists","namespacePath","listTypes","searchPath"],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -0,0 +1,6 @@
+export * from './interface';
+export * from './events';
+export * from './errors';
+export * from './observable';
+export * from './filesystem';
+export * from './memory';

package/dist/storage/interface.d.ts

@@ -0,0 +1,109 @@
+import { BaseEntity } from '../schema/base';
+import { SchemaRegistry } from '../schema/registry';
+/**
+ * Filter options for querying entities.
+ */
+export interface EntityFilter {
+    /** Filter by entity type(s) */
+    type?: string | string[];
+    /** Filter by namespace */
+    namespace?: string;
+    /** Filter by specific IDs */
+    ids?: string[];
+    /** Text search across name and searchable fields */
+    search?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Options for creating a storage provider.
+ */
+export interface StorageProviderOptions {
+    /** Schema registry for validation */
+    registry: SchemaRegistry;
+    /** Default namespace for operations */
+    defaultNamespace?: string;
+    /** Whether to prevent writes */
+    readonly?: boolean;
+}
+/**
+ * Generic storage provider interface.
+ * Implementations work with any entity type via the schema registry.
+ */
+export interface StorageProvider {
+    /**
+     * Initialize the storage provider.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Check if storage is accessible.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get a single entity by type and ID.
+     * Returns undefined if not found.
+     */
+    get<T extends BaseEntity>(type: string, id: string, namespace?: string): Promise<T | undefined>;
+    /**
+     * Get all entities of a type.
+     */
+    getAll<T extends BaseEntity>(type: string, namespace?: string): Promise<T[]>;
+    /**
+     * Find entities matching a filter.
+     */
+    find<T extends BaseEntity>(filter: EntityFilter): Promise<T[]>;
+    /**
+     * Check if an entity exists.
+     */
+    exists(type: string, id: string, namespace?: string): Promise<boolean>;
+    /**
+     * Count entities matching a filter.
+     */
+    count(filter: EntityFilter): Promise<number>;
+    /**
+     * Save an entity (create or update).
+     * Entity is validated against its registered schema.
+     * Returns the saved entity with updated metadata.
+     */
+    save<T extends BaseEntity>(entity: T, namespace?: string): Promise<T>;
+    /**
+     * Delete an entity.
+     * Returns true if entity existed and was deleted.
+     */
+    delete(type: string, id: string, namespace?: string): Promise<boolean>;
+    /**
+     * Save multiple entities in batch.
+     */
+    saveBatch<T extends BaseEntity>(entities: T[], namespace?: string): Promise<T[]>;
+    /**
+     * Delete multiple entities in batch.
+     */
+    deleteBatch(refs: Array<{
+        type: string;
+        id: string;
+    }>, namespace?: string): Promise<number>;
+    /**
+     * List available namespaces.
+     */
+    listNamespaces(): Promise<string[]>;
+    /**
+     * Check if a namespace exists.
+     */
+    namespaceExists(namespace: string): Promise<boolean>;
+    /**
+     * List entity types that have data in a namespace.
+     */
+    listTypes(namespace?: string): Promise<string[]>;
+    /** Provider name (e.g., 'filesystem', 'memory') */
+    readonly name: string;
+    /** Storage location info */
+    readonly location: string;
+    /** Schema registry reference */
+    readonly registry: SchemaRegistry;
+}

package/dist/storage/memory.d.ts

@@ -0,0 +1,7 @@
+import { StorageProvider, StorageProviderOptions } from './interface';
+import { BaseEntity } from '../schema/base';
+export interface MemoryProviderOptions extends StorageProviderOptions {
+    /** Initial data to populate */
+    initialData?: BaseEntity[];
+}
+export declare const createMemoryProvider: (options: MemoryProviderOptions) => StorageProvider;