@jointhedots/gear 1.1.18 → 1.2.2

package/esm/core/schema/zod.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import {} from "./schema.js";
+// =============================================================================
+// ZodService - Service Reference Type (External Spec)
+// =============================================================================
+export class ZodService {
+    $spec;
+    version;
+    _type = "ZodService";
+    constructor($spec, version) {
+        this.$spec = $spec;
+        this.version = version;
+    }
+    parse(data) {
+        if (typeof data !== "object" || data === null)
+            throw new Error(`Expected object, received ${typeof data}`);
+        return data;
+    }
+    safeParse(data) {
+        try {
+            return { success: true, data: this.parse(data) };
+        }
+        catch (e) {
+            return { success: false, error: e };
+        }
+    }
+    toJSONSchema() {
+        return { type: "service", $spec: this.$spec, ...(this.version && { version: this.version }) };
+    }
+    static create($spec, version) { return new ZodService($spec, version); }
+}
+export const zService = ZodService.create;
+// =============================================================================
+// Zod → JSON Schema (using Zod 4 native toJSONSchema with custom override)
+// =============================================================================
+export function zodToJSONSchema(schema) {
+    if (schema instanceof ZodService)
+        return schema.toJSONSchema();
+    return z.toJSONSchema(schema, {
+        unrepresentable: "any",
+        override: ({ zodSchema, jsonSchema }) => {
+            // Handle ZodService wrapped in other types via metadata
+            const meta = zodSchema._zod?.def?.meta;
+            if (meta?.$spec) {
+                Object.assign(jsonSchema, meta.toServiceSchema());
+            }
+        }
+    });
+}
+// =============================================================================
+// JSON Schema → Zod (using Zod 4 native fromJSONSchema)
+// =============================================================================
+export function jsonSchemaToZod(schema) {
+    if (!schema || !Object.keys(schema).length)
+        return z.any();
+    // Handle custom "service" type not supported by standard JSON Schema
+    if (schema.type === "service") {
+        const s = schema;
+        return zService(s.$spec, s.version);
+    }
+    return z.fromJSONSchema(schema);
+}
+export function validate(schema, data) {
+    const zs = schema instanceof z.ZodType ? schema : jsonSchemaToZod(schema);
+    const r = zs.safeParse(data);
+    return r.success
+        ? { success: true, data: r.data }
+        : { success: false, errors: r.error.issues.map(i => ({ path: i.path.map(String), message: i.message, code: i.code })) };
+}
+export function validateOrThrow(schema, data) {
+    const zs = schema instanceof z.ZodType ? schema : jsonSchemaToZod(schema);
+    return zs.parse(data);
+}
+export function generateTypeScript(schema, name, opts = {}) {
+    const { comments = true, indent = "  ", export: exp = true } = opts;
+    const ex = exp ? "export " : "";
+    const desc = comments && schema.description ? `/** ${schema.description} */\n` : "";
+    if (schema.type === "service") {
+        const s = schema;
+        const specComment = comments ? `${indent}/** @spec ${s.$spec}${s.version ? ` @version ${s.version}` : ""} */\n` : "";
+        return `${desc}${ex}interface ${name} {\n${specComment}${indent}[key: string]: unknown\n}`;
+    }
+    return `${desc}${ex}type ${name} = ${toTS(schema, indent, 0)}`;
+}
+const toTS = (s, ind, d) => {
+    const base = ind.repeat(d), inner = ind.repeat(d + 1);
+    if (s.const !== undefined)
+        return JSON.stringify(s.const);
+    if (s.enum)
+        return s.enum.map(v => JSON.stringify(v)).join(" | ");
+    if (s.oneOf)
+        return s.oneOf.map(x => toTS(x, ind, d)).join(" | ");
+    if (s.anyOf)
+        return s.anyOf.map(x => toTS(x, ind, d)).join(" | ");
+    if (s.allOf)
+        return s.allOf.map(x => toTS(x, ind, d)).join(" & ");
+    switch (s.type) {
+        case "string": return "string";
+        case "number":
+        case "integer": return "number";
+        case "boolean": return "boolean";
+        case "null": return "null";
+        case "array":
+            if (Array.isArray(s.items))
+                return `[${s.items.map(i => toTS(i, ind, d)).join(", ")}]`;
+            return `${s.items ? toTS(s.items, ind, d) : "any"}[]`;
+        case "object":
+            if (!s.properties && s.additionalProperties && typeof s.additionalProperties === "object")
+                return `Record<string, ${toTS(s.additionalProperties, ind, d)}>`;
+            if (!s.properties)
+                return "object";
+            const req = s.required ?? [];
+            const props = Object.entries(s.properties).map(([k, v]) => `${inner}${k}${req.includes(k) ? "" : "?"}: ${toTS(v, ind, d + 1)}`);
+            if (typeof s.additionalProperties === "object" && Object.keys(s.additionalProperties).length)
+                props.push(`${inner}[key: string]: ${toTS(s.additionalProperties, ind, d + 1)}`);
+            return `{\n${props.join("\n")}\n${base}}`;
+        case "function": return "Function";
+        case "view":
+        case "display":
+        case "element": return "React.ReactNode";
+        default: return "any";
+    }
+};
+// =============================================================================
+// Re-exports
+// =============================================================================
+export { z };

package/esm/core/services/mod.d.ts

@@ -0,0 +1,5 @@
+export * from "./service-definitions.ts";
+export * from "./service-points.ts";
+export * from "./service-specification.ts";
+export * from "./service-accessor.ts";
+export * from "./settings.ts";

package/esm/core/services/mod.js

@@ -0,0 +1,5 @@
+export * from "./service-definitions.js";
+export * from "./service-points.js";
+export * from "./service-specification.js";
+export * from "./service-accessor.js";
+export * from "./settings.js";

package/esm/core/services/service-accessor.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentEntry } from "../components/manifold.ts";
+export type ServiceType = string;
+export declare class ServiceAccessor<Instance extends any, Spec extends any> {
+    resource: string;
+    definition: any;
+    private constructor();
+    /** Synchronously retrieves the service instance from the given component entry. Returns undefined if the resource is not available. */
+    get(entry: ComponentEntry): Instance;
+    /** Asynchronously fetches the service instance from the given component entry, waiting until the resource becomes available. */
+    fetch(entry: ComponentEntry): Promise<Instance>;
+    /** Returns the specification/configuration associated with this service from the given component entry. */
+    spec(entry: ComponentEntry): Spec;
+    /** Creates a child service accessor scoped under this service's resource path. */
+    subservice<T extends any>(name: string): ServiceAccessor<T, Spec>;
+    /** Factory method that creates a new ServiceAccessor for the given resource name and optional definition. */
+    static About<Instance extends any, Spec extends any>(resource: string, definition?: any): ServiceAccessor<Instance, Spec>;
+}

package/esm/core/services/service-accessor.js

@@ -0,0 +1,20 @@
+export class ServiceAccessor {
+    resource;
+    definition;
+    constructor(resource, definition) {
+        this.resource = resource;
+        this.definition = definition;
+    }
+    /** Synchronously retrieves the service instance from the given component entry. Returns undefined if the resource is not available. */
+    get(entry) { return entry.getResource(this.resource)?.get(); }
+    /** Asynchronously fetches the service instance from the given component entry, waiting until the resource becomes available. */
+    fetch(entry) { return entry.fetchResource(this.resource); }
+    /** Returns the specification/configuration associated with this service from the given component entry. */
+    spec(entry) { return entry.acquireResource(this.resource)?.spec; }
+    /** Creates a child service accessor scoped under this service's resource path. */
+    subservice(name) { return ServiceAccessor.About(`${this.resource}.${name}`); }
+    /** Factory method that creates a new ServiceAccessor for the given resource name and optional definition. */
+    static About(resource, definition = null) {
+        return new ServiceAccessor(resource, definition);
+    }
+}

package/esm/core/services/service-definitions.d.ts

@@ -0,0 +1,37 @@
+import type { ServiceSchema } from "../schema/schema.ts";
+import { ZodService } from "../schema/zod.ts";
+import type { ZodType } from "zod";
+import { type ServiceSpecification, type ServiceCompatibility } from "./service-specification.ts";
+/**
+ * ServiceDefinition is a concrete definition linking a specification to implementation.
+ *
+ * @template I - The TypeScript interface type this service implements
+ * @template P - The type of properties (hyperparameters) for service speci alization
+ */
+export interface ServiceDefinition<I, P = unknown> {
+    /** Reference to the service specification */
+    $spec: string;
+    /** Version of the specification this definition implements */
+    version: string;
+    /** Zod schema for validating properties */
+    properties?: ZodType<P>;
+    /** Check if the service is compatible for assignement with an other definition */
+    isAssignable(from: ServiceDefinition<I>): any;
+}
+export type ServiceInterface<T> = T extends ServiceDefinition<infer I, any> ? I : never;
+/**
+ * Get ZodService type from a service definition
+ */
+export declare function getServiceZod<I>(def: ServiceDefinition<I>): ZodService<I>;
+/**
+ * Get ServiceSchema (JSON Schema representation) from a service definition
+ */
+export declare function getServiceSchema<I, P>(def: ServiceDefinition<I, P>): ServiceSchema;
+/**
+ * Get full ServiceSchema including attributes schema from a specification
+ */
+export declare function getServiceSchemaFromSpec<I, A>(spec: ServiceSpecification<I, A>): ServiceSchema;
+/**
+ * Check if a service definition matches a specification
+ */
+export declare function matchesSpecification<I, A>(def: ServiceDefinition<I, A>, spec: ServiceSpecification<I, A>): ServiceCompatibility;

package/esm/core/services/service-definitions.js

@@ -0,0 +1,44 @@
+import { ZodService } from "../schema/zod.js";
+import { checkVersionCompatibility } from "./service-specification.js";
+// =============================================================================
+// Service Factory Functions
+// =============================================================================
+/**
+ * Get ZodService type from a service definition
+ */
+export function getServiceZod(def) {
+    return ZodService.create(def.$spec, def.version);
+}
+/**
+ * Get ServiceSchema (JSON Schema representation) from a service definition
+ */
+export function getServiceSchema(def) {
+    return {
+        type: "service",
+        $spec: def.$spec,
+        version: def.version,
+    };
+}
+/**
+ * Get full ServiceSchema including attributes schema from a specification
+ */
+export function getServiceSchemaFromSpec(spec) {
+    const schema = {
+        type: "service",
+        $spec: spec.$spec,
+        version: spec.version,
+    };
+    return schema;
+}
+/**
+ * Check if a service definition matches a specification
+ */
+export function matchesSpecification(def, spec) {
+    if (def.$spec !== spec.$spec) {
+        return {
+            compatible: false,
+            reason: `Specification mismatch: definition uses "${def.$spec}", expected "${spec.$spec}"`
+        };
+    }
+    return checkVersionCompatibility(spec.version, def.version, spec.minCompatibleVersion);
+}

package/esm/core/services/service-points.d.ts

@@ -0,0 +1,40 @@
+import { type ComponentID } from "../components/components.ts";
+import { type ILogDispatcher, type LogObject } from "../logging/mod.ts";
+import { ServiceAccessor, type ServiceType } from "./service-accessor.ts";
+export declare const ServicePoints: Map<string, ServicePoint>;
+export type ServicePointID = string;
+export type ServicePointProperties = {
+    title?: string;
+    multiple?: boolean;
+    alternative?: ServicePointID;
+};
+export type ServicePointSetting = {
+    id: ServicePointID;
+    providers: ComponentID[];
+    properties: ServicePointProperties;
+};
+export type ServiceChangeHandler = (service: ServicePoint) => void;
+export declare class ServicePoint<IService = unknown> implements ILogDispatcher {
+    descriptor: ServicePointSetting;
+    service: ServiceType;
+    name: string;
+    services: IService[];
+    loading: Promise<IService[]>;
+    ready: boolean;
+    failure: Error;
+    constructor(descriptor: ServicePointSetting);
+    get id(): string;
+    get multiple(): boolean;
+    fetch(): Promise<IService[]>;
+    reset(descriptor: ServicePointSetting): Promise<this>;
+    override(providers: ComponentID[]): void;
+    notifyError(error: Error): void;
+    notifyObject(object: LogObject): void;
+}
+export declare function listenServicePoints(handler: ServiceChangeHandler): ServiceChangeHandler;
+export declare function unlistenServicePoints(handler: ServiceChangeHandler): void;
+export declare function acquireServicePointDescriptor(id: string): ServicePointSetting;
+export declare function updateServicePointDescriptor(id: string, properties: ServicePointProperties): ServicePointSetting;
+export declare function getServicePoint<IService>(id: string): ServicePoint<IService>;
+export declare function acquireServicePoint<IService>(id: string): ServicePoint<IService>;
+export declare function createServicePoint<S extends any, D extends any>(service: ServiceAccessor<S, D>, name: ServicePointID, properties?: ServicePointProperties): ServicePoint<S>;

package/esm/core/services/service-points.js

@@ -0,0 +1,164 @@
+import { acquireComponent, ComponentsRegistry } from "../components/manifold.js";
+import {} from "../components/components.js";
+import { getSettings, listenSettings, WriteMode } from "./settings.js";
+import { Log } from "../logging/mod.js";
+import { ServiceAccessor } from "./service-accessor.js";
+export const ServicePoints = new Map();
+const ServiceChangeHandlers = new Set();
+export class ServicePoint {
+    descriptor;
+    service = "";
+    name = "";
+    services = [];
+    loading = null;
+    ready = false;
+    failure = null;
+    constructor(descriptor) {
+        this.descriptor = descriptor;
+        const [service, name] = descriptor.id.split("/");
+        this.service = service;
+        this.name = name;
+    }
+    get id() {
+        return this.descriptor.id;
+    }
+    get multiple() {
+        return this.descriptor?.properties?.multiple || false;
+    }
+    async fetch() {
+        if (this.ready) {
+            return this.services;
+        }
+        if (!this.loading) {
+            this.loading = new Promise(async (resolve) => {
+                const { descriptor } = this;
+                const { providers } = this.descriptor;
+                const services = await fetchComponentsService(providers, this.service, this.id, this);
+                if (descriptor === this.descriptor) {
+                    this.services = services;
+                    this.ready = true;
+                    this.loading = null;
+                    resolve(this.services);
+                }
+                else {
+                    resolve(this.fetch());
+                }
+            });
+        }
+        return this.loading;
+    }
+    async reset(descriptor) {
+        if (this.descriptor !== descriptor) {
+            this.descriptor = descriptor;
+            if (this.loading || this.ready || this.failure) {
+                this.failure = null;
+                this.loading = null;
+                this.ready = false;
+                ServiceChangeHandlers.forEach(l => l(this));
+                await this.fetch();
+            }
+            ServiceChangeHandlers.forEach(l => l(this));
+        }
+        return this;
+    }
+    override(providers) {
+        const settings = getSettings();
+        const descriptor = settings.get("service_points", this.id);
+        settings.set("service_points", this.id, { ...descriptor, providers }, WriteMode.Temporary);
+    }
+    notifyError(error) {
+        this.failure = error;
+        Log.error(error);
+    }
+    notifyObject(object) {
+        Log.send(object);
+    }
+}
+export function listenServicePoints(handler) {
+    ServiceChangeHandlers.add(handler);
+    return handler;
+}
+export function unlistenServicePoints(handler) {
+    ServiceChangeHandlers.delete(handler);
+}
+ComponentsRegistry.listen((component) => {
+    for (const service of ServicePoints.values()) {
+        if (service.descriptor.providers?.includes(component.id)) {
+            ServiceChangeHandlers.forEach(l => l(service));
+        }
+    }
+});
+async function fetchComponentsService(components_ids, service, servicepoint, log) {
+    const services = [];
+    if (Array.isArray(components_ids) && components_ids.length > 0) {
+        for (const component_id of components_ids) {
+            const component = acquireComponent(component_id);
+            if (await component.fetch()) {
+                const srv = await component.acquireResource(service).fetch();
+                if (srv) {
+                    services.push(srv);
+                }
+                else {
+                    log.notifyError(new Error(`ServicePoint '${servicepoint}': component '${component_id}' not implement service '${service}'`));
+                }
+            }
+            else {
+                log.notifyError(new Error(`ServicePoint '${servicepoint}': component '${component_id}' not found`));
+            }
+        }
+    }
+    return services;
+}
+export function acquireServicePointDescriptor(id) {
+    const settings = getSettings();
+    let desc = settings.get("service_points", id);
+    if (!desc)
+        desc = { id, providers: [], properties: {} };
+    return desc;
+}
+export function updateServicePointDescriptor(id, properties) {
+    const settings = getSettings();
+    let desc = settings.get("service_points", id);
+    if (desc) {
+        let hasChanged = false;
+        for (const key in properties) {
+            const value = properties[key];
+            if (value !== undefined && desc[key] != value) {
+                desc[key] = value;
+                hasChanged = true;
+            }
+        }
+        hasChanged && settings.set("service_points", id, desc);
+    }
+    else {
+        desc = { id, providers: [], properties };
+        settings.set("service_points", id, desc);
+    }
+    return desc;
+}
+listenSettings((group, id) => {
+    if (group === "service_points") {
+        const svc = ServicePoints.get(id);
+        if (svc) {
+            const desc = getSettings().get("service_points", id);
+            svc.reset(desc);
+            console.log("[Update Service Point]", id);
+        }
+    }
+});
+export function getServicePoint(id) {
+    return ServicePoints.get(id);
+}
+export function acquireServicePoint(id) {
+    let svc = ServicePoints.get(id);
+    if (!svc) {
+        svc = new ServicePoint(acquireServicePointDescriptor(id));
+        ServicePoints.set(svc.id, svc);
+    }
+    return svc;
+}
+export function createServicePoint(service, name, properties) {
+    const id = service.resource + "/" + name;
+    updateServicePointDescriptor(id, properties);
+    return acquireServicePoint(id);
+}

package/esm/core/services/service-specification.d.ts

@@ -0,0 +1,52 @@
+import type { JSONSchema } from "../schema/schema.ts";
+import type { ZodType } from "zod";
+/**
+ * ServiceSpecification defines the metadata and schema for a service interface.
+ * It describes the contract that providers must implement and consumers can rely on.
+ *
+ * @template I - The TypeScript interface type this service represents
+ * @template P - The type of properties (hyperparameters) for service specialization
+ */
+export interface ServiceSpecification<I = unknown, P = unknown> {
+    /** Unique identifier for the service specification (URI or qualified name) */
+    $spec: string;
+    /** Semantic version of the specification (e.g., "1.0.0") */
+    version: string;
+    /**
+     * JSON Schema defining the service interface including:
+     * - title, description (metadata)
+     * - properties (hyperparameters for service specialization)
+     * - All standard JSON Schema validation rules
+     */
+    schema?: JSONSchema;
+    /**
+     * Zod schema for runtime validation and compile-time type inference.
+     * Bridges runtime validation with TypeScript's static type system.
+     */
+    properties?: ZodType<P>;
+    /** Category or domain the service belongs to */
+    category?: string;
+    /** Tags for discovery and filtering */
+    tags?: string[];
+    /** Minimum compatible version for consumers */
+    minCompatibleVersion?: string;
+}
+/**
+ * Result of checking compatibility between consumer and provider
+ */
+export interface ServiceCompatibility {
+    /** Whether the service is compatible */
+    compatible: boolean;
+    /** Reason for incompatibility if not compatible */
+    reason?: string;
+    /** Warnings about potential issues */
+    warnings?: string[];
+}
+/**
+ * Check if a provider version is compatible with a consumer's required version
+ */
+export declare function checkVersionCompatibility(requiredVersion: string, providedVersion: string, minCompatibleVersion?: string): ServiceCompatibility;
+/**
+ * Create a service specification with full metadata
+ */
+export declare function defineServiceSpec<I = unknown, P = unknown>(spec: ServiceSpecification<I, P>): ServiceSpecification<I, P>;

package/esm/core/services/service-specification.js

@@ -0,0 +1,59 @@
+/**
+ * Check if a provider version is compatible with a consumer's required version
+ */
+export function checkVersionCompatibility(requiredVersion, providedVersion, minCompatibleVersion) {
+    const required = parseVersion(requiredVersion);
+    const provided = parseVersion(providedVersion);
+    // Exact match is always compatible
+    if (requiredVersion === providedVersion) {
+        return { compatible: true };
+    }
+    // Major version must match for compatibility
+    if (required.major !== provided.major) {
+        return {
+            compatible: false,
+            reason: `Major version mismatch: required ${required.major}.x, provided ${provided.major}.x`
+        };
+    }
+    // Provider version must be >= required version
+    if (provided.minor < required.minor) {
+        return {
+            compatible: false,
+            reason: `Provider version ${providedVersion} is older than required ${requiredVersion}`
+        };
+    }
+    // Check minimum compatible version if specified
+    if (minCompatibleVersion) {
+        const minCompat = parseVersion(minCompatibleVersion);
+        if (required.major < minCompat.major ||
+            (required.major === minCompat.major && required.minor < minCompat.minor)) {
+            return {
+                compatible: false,
+                reason: `Required version ${requiredVersion} is below minimum compatible version ${minCompatibleVersion}`
+            };
+        }
+    }
+    return {
+        compatible: true,
+        warnings: provided.minor > required.minor
+            ? [`Provider version ${providedVersion} is newer than required ${requiredVersion}`]
+            : undefined
+    };
+}
+function parseVersion(version) {
+    const parts = version.split(".").map(Number);
+    return {
+        major: parts[0] || 0,
+        minor: parts[1] || 0,
+        patch: parts[2] || 0
+    };
+}
+// =============================================================================
+// Service Specification Factory
+// =============================================================================
+/**
+ * Create a service specification with full metadata
+ */
+export function defineServiceSpec(spec) {
+    return spec;
+}

package/esm/core/services/settings.d.ts

@@ -0,0 +1,29 @@
+export type CommonSetting = Record<string, any>;
+export type SettingGroup = "service_points" | "components" | "shareds";
+export type SettingStores<T> = {
+    [id in SettingGroup]: Record<string, T>;
+};
+export declare enum WriteMode {
+    Default = 0,
+    Reset = 1,
+    Temporary = 2
+}
+export declare class AccountSettings {
+    readonly name: string;
+    key: string;
+    stores: SettingStores<string>;
+    temporaries: SettingStores<string>;
+    settings: SettingStores<CommonSetting>;
+    constructor(name: string);
+    get<T = any>(group: SettingGroup, key: string): T;
+    set<T = any>(group: SettingGroup, key: string, descriptor: T, mode?: WriteMode): boolean;
+    list(group: SettingGroup): string[];
+    read(key: string): string;
+    write(group: SettingGroup, key: string, data: string, mode: WriteMode): boolean;
+    restore(stores: SettingStores<string>): void;
+}
+type SettingsChangeHandler = (group: SettingGroup, id: string) => void;
+export declare function getSettings(): AccountSettings;
+export declare function listenSettings(handler: SettingsChangeHandler): SettingsChangeHandler;
+export declare function unlistenSettings(handler: SettingsChangeHandler): void;
+export {};