@adaas/a-frame 0.0.22 → 0.1.1

package/src/lib/A-Frame/A-Frame.meta.ts

@@ -0,0 +1,27 @@
+import { A_ComponentMeta, A_Context, A_Meta } from "@adaas/a-concept";
+import { A_FrameMetaTarget } from "./A-Frame.types";
+import { A_FrameIndexMeta } from "./A-FrameIndex.meta";
+
+export class A_FrameMeta extends A_ComponentMeta {
+
+    getMetaFor(target: A_FrameMetaTarget): A_FrameIndexMeta {
+
+        const targetSpace = this.get('A_Frame_CONFIGURATIONS_META' as any) || new Map<A_FrameMetaTarget, A_FrameIndexMeta>();
+
+        if (!targetSpace.has(target)) {
+            targetSpace.set(target, new A_FrameIndexMeta());
+            this.set('A_Frame_CONFIGURATIONS_META' as any, targetSpace);
+        }
+
+        return targetSpace.get(target)!;
+    }
+
+
+    seMetaFor(target: A_FrameMetaTarget, meta: A_FrameIndexMeta): void {
+        const targetSpace = this.get('A_Frame_CONFIGURATIONS_META' as any) || new Map<A_FrameMetaTarget, A_FrameIndexMeta>();
+
+        targetSpace.set(target, meta);
+
+        this.set('A_Frame_CONFIGURATIONS_META' as any, targetSpace);
+    }
+}

package/src/lib/{components/Index.component.ts/Index.types.ts → A-Frame/A-Frame.types.ts}

@@ -1,16 +1,37 @@
 import { A_Component, A_Container, A_Entity, A_Fragment, A_TYPES__Component_Constructor, A_TYPES__Container_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor, A_TYPES__Required } from "@adaas/a-concept"
-import { A_Namespace } from "src/lib/entities/Namespace/Namespace.entity"
+import { A_FrameNamespace } from "../A-FrameNamespace"
 
 
-export type A_Frame_IndexOptions = {
-    name?: string,
-    namespace?: string | A_Namespace
+export type A_FrameOptions = {
+    namespace?: string
     description?: string
 }
 
 
+export type A_FrameDefineOptions<T extends Record<string, any> = Record<string, any>> = {
+    /**
+     * The description of the Method or Class to be indexed. Uses for the better explanation and retrieval strategy 
+     */
+    description?: string,
+    /**
+     * Define Namespace to separate and group together related components, entities and containers.
+     * 
+     * [!] Namespace is a hard separation between groups.
+     */
+    namespace?: string | A_FrameNamespace
+    /***
+     * Optional parameters that can be used to store any additional information about the component, entity or container.
+     * This information can be used for the better retrieval strategy or for the better explanation of the component, entity or container.
+     */
+    metadata?: T,
+    /**
+     * Can add a custom way of explaining the component, entity or container, so it can be used in the better retrieval strategy.
+     */
+    examples?: string[]
+}
 
-export type A_Frame_IndexMetaTarget = A_TYPES__Container_Constructor
+
+export type A_FrameMetaTarget = A_TYPES__Container_Constructor
     | A_TYPES__Entity_Constructor
     | A_TYPES__Component_Constructor
     | A_TYPES__Fragment_Constructor
@@ -25,7 +46,7 @@ export type A_Frame_IndexMetaTarget = A_TYPES__Container_Constructor
 /**
  * Indicates a type of Feature Define decorator
  */
-export type A_Frame_IndexDecoratorDescriptor =
+export type A_FrameDecoratorDescriptor =
     TypedPropertyDescriptor<(...args: any[]) => any>
     | TypedPropertyDescriptor<(...args: any[]) => any>
     | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
@@ -37,7 +58,7 @@ export type A_Frame_IndexDecoratorDescriptor =
  * 
  * [!] The feature can be defined on Container, Entity, Component or Command
  */
-export type A_Frame_IndexDecoratorTarget = A_Frame_IndexMetaTarget
+export type A_FrameDecoratorTarget = A_FrameMetaTarget
     | A_Component
     | A_Container
     | A_Entity
@@ -45,7 +66,7 @@ export type A_Frame_IndexDecoratorTarget = A_Frame_IndexMetaTarget
 /**
  * Targets types that can be indexed
  */
-export enum A_Frame_IndexTargetType {
+export enum A_FrameTargetType {
     COMPONENT = 'component',
     ENTITY = 'entity',
     CONTAINER = 'container',
@@ -57,7 +78,7 @@ export enum A_Frame_IndexTargetType {
  * A type of Meta information stored by Index decorator
  * This information is used by A-Context to build a proper index structure
  */
-export type A_Frame_IndexDecoratorMeta = {
+export type A_FrameDecoratorMeta = {
     /**
      * Component name
      */
@@ -69,15 +90,15 @@ export type A_Frame_IndexDecoratorMeta = {
     /**
      * Type of the component
      */
-    type: A_Frame_IndexTargetType,
+    type: A_FrameTargetType,
     /**
      * Namespace for the component
      */
-    namespace?: string | A_Namespace,
+    namespace?: string | A_FrameNamespace
     /**
      * Constructor reference
      */
-    constructor: A_Frame_IndexDecoratorTarget
+    constructor: A_FrameDecoratorTarget
 }
 
 
@@ -87,7 +108,7 @@ export type A_Frame_IndexDecoratorMeta = {
 /**
  * Indicates a type of Feature Define decorator
  */
-export type A_Frame_IndexNamespaceDecoratorDescriptor =
+export type A_FrameNamespaceDecoratorDescriptor =
     TypedPropertyDescriptor<(...args: any[]) => any>
     | TypedPropertyDescriptor<(...args: any[]) => any>
     | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
@@ -99,7 +120,7 @@ export type A_Frame_IndexNamespaceDecoratorDescriptor =
  * 
  * [!] The feature can be defined on Container, Entity, Component or Command
  */
-export type A_Frame_IndexNamespaceDecoratorTarget = A_Container
+export type A_FrameNamespaceDecoratorTarget = A_Container
     | A_Entity
     | A_Component
     | A_Fragment
@@ -116,17 +137,31 @@ export type A_Frame_IndexNamespaceDecoratorTarget = A_Container
 // ---------------------------------------------------------------------------
 
 
-export type A_Frame_IndexConfigurationsMetaType = {
+export type A_FrameIndexMetaType = {
     namespaces: string,
     descriptions: string,
     type: string,
     name: string,
-    methods: Map<string, A_Frame_IndexConfigurationsMetaMethodMeta>
+    methods: Map<string, A_FrameIndexMetaMethodMeta>
 }
 
 
-export type A_Frame_IndexConfigurationsMetaMethodMeta = {
+export type A_FrameIndexMetaMethodMeta = {
     name: string,
     description?: string,
     methodName: string
+}
+
+
+
+
+export type A_FrameNamespaceOptions = {
+    /**
+     * Must have UNIQUE name of the Namespace. This is used for the indexing and retrieval strategy. It should be descriptive and concise.
+     */
+    name: string,
+    /**
+     * The description of the Namespace to be indexed. Uses for the better explanation and retrieval strategy
+     */
+    description?: string,
 }

package/src/lib/A-Frame/decorators/A-FrameDefine.decorator.ts

@@ -0,0 +1,104 @@
+import { A_CommonHelper, A_Context, A_Meta, A_TypeGuards } from "@adaas/a-concept";
+import { A_FrameDecoratorTarget, A_FrameTargetType, A_FrameDecoratorDescriptor, A_FrameMetaTarget, A_FrameDefineOptions } from "../A-Frame.types";
+import { A_FrameTypeGuard } from "../A-Frame.guard";
+import { A_FrameError } from "../A-Frame.error";
+import { A_FrameIndex } from "@adaas/a-frame/index";
+import { A_FrameDefinition } from "@adaas/a-frame/definition";
+import { A_FrameNamespace } from "@adaas/a-frame/namespace";
+
+export function A_FrameDefineDecorator(
+    config: A_FrameDefineOptions
+) {
+    return function (
+        target: A_FrameDecoratorTarget,
+        propertyKey?: string | symbol,
+        descriptor?: A_FrameDecoratorDescriptor
+    ): any {
+        let componentType: A_FrameTargetType;
+
+        switch (true) {
+            case !!propertyKey && !!descriptor:
+                componentType = A_FrameTargetType.METHOD;
+                break;
+            case A_TypeGuards.isComponentConstructor(target) || A_TypeGuards.isComponentInstance(target):
+                componentType = A_FrameTargetType.COMPONENT;
+                break;
+            case A_TypeGuards.isContainerConstructor(target) || A_TypeGuards.isContainerInstance(target):
+                componentType = A_FrameTargetType.CONTAINER;
+                break;
+            case A_TypeGuards.isEntityConstructor(target) || A_TypeGuards.isEntityInstance(target):
+                componentType = A_FrameTargetType.ENTITY;
+                break;
+            case A_TypeGuards.isFragmentConstructor(target) || A_TypeGuards.isFragmentInstance(target):
+                componentType = A_FrameTargetType.FRAGMENT;
+                break;
+            default:
+                throw new A_FrameError(
+                    A_FrameError.InvalidTarget,
+                    `@A_Frame.Define decorator cannot be applied to the target.`
+                );
+        }
+        const namespace = config.namespace
+            ? config.namespace instanceof A_FrameNamespace
+                ? config.namespace
+                : A_FrameIndex.getNamespace(config.namespace) || new A_FrameNamespace({
+                    name: config.namespace,
+                })
+            : A_FrameIndex.getDefaultNamespace();
+
+
+        // Handle method decorator case
+        if (!!propertyKey && !!descriptor) {
+            // For methods, target is the class prototype
+            const targetClass = target.constructor as A_FrameMetaTarget;
+            const methodName = String(propertyKey);
+
+            const source = (descriptor.value as Function).toString();
+
+            // Add to methods array
+            A_FrameIndex.addDefinition(new A_FrameDefinition({
+                name: methodName,
+                dependency: targetClass.name,
+                description: config.description,
+                source: source,
+                metadata: config.metadata,
+                type: A_FrameTargetType.METHOD,
+                namespace: namespace
+            }));
+
+            return descriptor;
+        }
+
+        // Handle class decorator case
+        if (!A_FrameTypeGuard.isAllowedTarget(target)) {
+            throw new A_FrameError(
+                A_FrameError.InvalidTarget,
+                `@A_Frame.${componentType} decorator can only be applied to allowed targets.`
+            );
+        }
+
+        // for error messages
+        const componentName = A_CommonHelper.getComponentName(target);
+
+        const targetClass = A_FrameTypeGuard.getTargetConstructor(target);
+
+        // Check for pending namespace and description from other decorators
+        const source = target.toString();
+
+        A_FrameIndex.addDefinition(new A_FrameDefinition({
+            name: componentName,
+            description: config.description,
+            dependency: targetClass.name,
+            source: source,
+            metadata: config.metadata,
+            type: componentType,
+            namespace: namespace
+        }));
+
+        return target;
+
+    };
+}
+
+
+

package/src/lib/A-Frame/decorators/A-FrameNamespace.decorator.ts

@@ -0,0 +1,33 @@
+import { A_CommonHelper, A_Context, A_Meta, A_TypeGuards } from "@adaas/a-concept";
+import { A_FrameDecoratorTarget, A_FrameTargetType, A_FrameDecoratorDescriptor, A_FrameMetaTarget, A_FrameNamespaceOptions } from "../A-Frame.types";
+import { A_FrameError } from "../A-Frame.error";
+import { A_FrameIndex } from "@adaas/a-frame/index";
+import { A_FrameNamespace } from "@adaas/a-frame/namespace";
+
+export function A_FrameNamespaceDecorator(
+    config: Partial<A_FrameNamespaceOptions> = {}
+) {
+    return function (
+        target: A_FrameDecoratorTarget,
+        propertyKey?: string | symbol,
+        descriptor?: A_FrameDecoratorDescriptor
+    ): any {
+
+        if (!config.name)
+            throw new A_FrameError(
+                A_FrameError.InvalidConfiguration,
+                `@A_Frame.Namespace decorator requires a name in the configuration.`
+            );
+
+        const namespace = new A_FrameNamespace({
+            name: config.name,
+            description: config.description,
+        });
+
+
+        A_FrameIndex.addNamespace(namespace);
+    };
+}
+
+
+

package/src/lib/A-Frame/index.browser.ts

@@ -0,0 +1,10 @@
+export * from './A-Frame.component';
+export * from './A-Frame.context';
+export * from './A-Frame.types';
+export * from './A-Frame.error';
+// export * from './A-Frame.meta';
+export * from './A-Frame.guard';
+export * from './decorators/A-FrameDefine.decorator';
+export * from './decorators/A-FrameNamespace.decorator';
+
+export * from './A-Frame.component.env-browser';

package/src/lib/A-Frame/index.ts

@@ -0,0 +1,10 @@
+export * from './A-Frame.component';
+export * from './A-Frame.context';
+export * from './A-Frame.types';
+export * from './A-Frame.error';
+// export * from './A-Frame.meta';
+export * from './A-Frame.guard';
+export * from './decorators/A-FrameDefine.decorator';
+export * from './decorators/A-FrameNamespace.decorator';
+
+export * from './A-Frame.component.env-node';

package/src/lib/A-FrameBundle/A-FrameBundle.builder.env-node.ts

@@ -0,0 +1,95 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { A_Component } from '@adaas/a-concept';
+import { A_FrameBundle } from './A-FrameBundle.types';
+import { A_FRAME_BUNDLE_VERSION } from './A-FrameBundle.constants';
+import { A_FrameStorageCodec } from '../A-FrameStorage/A-FrameStorage.codec';
+import * as pkg from '../../../package.json';
+
+
+export interface A_FrameBundleBuilderOptions {
+    /** Source directory containing the encrypted `*.aframe` files (Node storage). */
+    storageDir: string;
+    /** Server version to embed in the bundle metadata. */
+    serverVersion: string;
+}
+
+
+/**
+ * A_FrameBundleBuilder — Node-only build-time helper.
+ *
+ * Reads the encrypted `*.aframe` files produced by Node storage and packages
+ * them into a single JSON (or generated TypeScript module) artifact that ships
+ * with the browser bundle. The browser bootstrap then seeds these blobs into
+ * `A_FrameBrowserStorageBlobs` so that read-only `definition.load()` /
+ * `namespace.load()` calls work without a filesystem.
+ */
+export class A_FrameBundleBuilder extends A_Component {
+
+    /** Read all `.aframe` files from a storage directory and serialise them. */
+    async build(opts: A_FrameBundleBuilderOptions): Promise<A_FrameBundle> {
+        const ext = A_FrameStorageCodec.fileExtension; // ".aframe"
+        const namespacesFile = `__namespaces${ext}`;
+
+        let entries: string[];
+        try {
+            entries = await fs.readdir(opts.storageDir);
+        } catch (err: any) {
+            if (err?.code === 'ENOENT') {
+                throw new Error(`A-Frame storage directory not found: ${opts.storageDir}`);
+            }
+            throw err;
+        }
+
+        const aframeFiles = entries.filter(f => f.endsWith(ext));
+
+        let namespaces: string | null = null;
+        const definitions: Record<string, string> = {};
+
+        for (const file of aframeFiles) {
+            const buf = await fs.readFile(path.join(opts.storageDir, file));
+            const b64 = buf.toString('base64');
+
+            if (file === namespacesFile) {
+                namespaces = b64;
+            } else {
+                const id = file.slice(0, -ext.length);
+                definitions[id] = b64;
+            }
+        }
+
+        return {
+            bundleVersion: A_FRAME_BUNDLE_VERSION,
+            aFrameVersion: (pkg as any).version || '0.0.0',
+            serverVersion: opts.serverVersion,
+            builtAt: new Date().toISOString(),
+            namespaces,
+            definitions,
+        };
+    }
+
+    /** Write the bundle to disk as a JSON file. */
+    async writeJSON(bundle: A_FrameBundle, outFile: string): Promise<void> {
+        await fs.mkdir(path.dirname(path.resolve(outFile)), { recursive: true });
+        await fs.writeFile(outFile, JSON.stringify(bundle, null, 2));
+    }
+
+    /**
+     * Emit a TypeScript module that exports the bundle as a typed constant.
+     * Useful for bundlers that prefer TS imports over JSON imports.
+     */
+    async writeTS(bundle: A_FrameBundle, outFile: string): Promise<void> {
+        const banner = '// AUTO-GENERATED by @adaas/a-frame — do not edit.\n';
+        const body =
+            `import type { A_FrameBundle } from '@adaas/a-frame';\n\n` +
+            `export const A_FRAME_BUNDLE: A_FrameBundle = ${JSON.stringify(bundle, null, 2)} as A_FrameBundle;\n`;
+        await fs.mkdir(path.dirname(path.resolve(outFile)), { recursive: true });
+        await fs.writeFile(outFile, banner + body);
+    }
+
+    /** Convenience: detect output format by extension and write. */
+    async writeAuto(bundle: A_FrameBundle, outFile: string): Promise<void> {
+        if (/\.tsx?$/.test(outFile)) return this.writeTS(bundle, outFile);
+        return this.writeJSON(bundle, outFile);
+    }
+}

package/src/lib/A-FrameBundle/A-FrameBundle.constants.ts

@@ -0,0 +1,5 @@
+/** Current bundle format revision. Bumped on incompatible structural changes. */
+export const A_FRAME_BUNDLE_VERSION = 1;
+
+/** Default file name when none is provided to the CLI. */
+export const A_FRAME_BUNDLE_DEFAULT_FILENAME = 'a-frame-bundle.json';

package/src/lib/A-FrameBundle/A-FrameBundle.types.ts

@@ -0,0 +1,31 @@
+/**
+ * Serialized A-Frame bundle artifact.
+ *
+ * Built by `A_FrameBundleBuilder` from a Node storage directory at build time
+ * (see CLI `--bundle <out>`). Loaded by `A_FrameBrowserStorageBlobs.seedFromBundle()`
+ * at app startup in the browser.
+ *
+ * Storage blobs are kept in their AES-256-GCM encrypted form — the consuming
+ * browser app must obtain the encryption key out-of-band (typically by
+ * authenticating against the A-Frame server with the user's token).
+ */
+export interface A_FrameBundle {
+    /** Bundle format version. Currently 1. */
+    bundleVersion: number;
+    /** A-Frame client library version that produced the bundle. */
+    aFrameVersion: string;
+    /** A-Frame server version this bundle was embedded against. */
+    serverVersion: string;
+    /** Build timestamp (ISO 8601). */
+    builtAt: string;
+    /**
+     * Base64-encoded contents of the `__namespaces.aframe` index file.
+     * `null` when no namespaces have been persisted yet.
+     */
+    namespaces: string | null;
+    /**
+     * Map of namespace id (file basename without extension) → base64-encoded
+     * contents of the corresponding `<namespace>.aframe` file.
+     */
+    definitions: Record<string, string>;
+}

package/src/lib/A-FrameBundle/index.browser.ts

@@ -0,0 +1,6 @@
+// Browser-safe surface — no filesystem access. Only types and constants.
+export type { A_FrameBundle } from './A-FrameBundle.types';
+export {
+    A_FRAME_BUNDLE_VERSION,
+    A_FRAME_BUNDLE_DEFAULT_FILENAME,
+} from './A-FrameBundle.constants';

package/src/lib/A-FrameBundle/index.ts

@@ -0,0 +1,7 @@
+export { A_FrameBundleBuilder } from './A-FrameBundle.builder.env-node';
+export type { A_FrameBundleBuilderOptions } from './A-FrameBundle.builder.env-node';
+export type { A_FrameBundle } from './A-FrameBundle.types';
+export {
+    A_FRAME_BUNDLE_VERSION,
+    A_FRAME_BUNDLE_DEFAULT_FILENAME,
+} from './A-FrameBundle.constants';