@componentonce/core 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @componentonce/core
+
+Renderer, framework, and storage agnostic contracts for trusted versioned components.
+
+## Definitions
+
+ComponentOnceDefinition carries four independent generic types:
+
+- implementation: opaque to core
+- Props: persisted/configured data
+- HostContext: arbitrary runtime capabilities/services owned by the host
+- Payload: arbitrary application/domain data for one invocation
+
+Every manifest has an exact id and version and may declare multiple requirements:
+
+    requirements: [
+      { name: "react", version: "19" },
+      { name: "my-app-sdk", version: "3" }
+    ]
+
+Core does not know what those capabilities mean.
+
+## Compatibility
+
+Hosts provide ComponentOnceCapability records before executing an implementation.
+
+assertComponentOnceCompatible verifies every requirement. Missing capability and incompatible version are separate typed errors. Exact name/version equality is the default. A host may supply ComponentOnceCapabilityCompatibility to implement another policy, such as accepting a compatible React range or application SDK major version.
+
+Core has no semver dependency and no React-specific compatibility logic.
+
+## Registries
+
+ComponentOnceRegistry instances are isolated. Exact id/version lookup is deterministic. Hosts may explicitly configure a default version, but registration never guesses that a newest-looking string should win.
+
+Duplicate exact versions throw by default; callers may explicitly keep the existing definition or replace it.
+
+## Loaders
+
+ComponentOnceLoader is an I/O-free adapter contract. Storage and transport implementations extend ComponentOnceLoadDescriptor with their own data. loadAndRegisterComponentOnce verifies that a loader returned the exact id/version requested before registration.

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/** An exact, immutable component identity used for deterministic lookup. */
+export interface ComponentOnceExactReference {
+    /** Host-independent component identity. */
+    readonly id: string;
+    /** Exact component implementation version. */
+    readonly version: string;
+}
+/** One named runtime or host capability required by a component implementation. */
+export interface ComponentOnceRequirement {
+    /** Stable capability name such as React, browser DOM, or an application SDK id. */
+    readonly name: string;
+    /** Requirement version interpreted by the host compatibility rule. */
+    readonly version: string;
+}
+/** One named runtime or API capability actually available from a host. */
+export interface ComponentOnceCapability {
+    /** Stable capability name. */
+    readonly name: string;
+    /** Version exposed by this host. */
+    readonly version: string;
+}
+/** Stable identity and compatibility metadata for one registered component implementation. */
+export interface ComponentOnceManifest extends ComponentOnceExactReference {
+    /** Optional human label for editor or catalog surfaces. */
+    readonly displayName?: string;
+    /** Runtime/application contracts which must all be satisfied before this component can run. */
+    readonly requirements?: readonly ComponentOnceRequirement[];
+}
+/** Optional validator used at an adapter boundary rather than on every render. */
+export type ComponentOnceValidator<T> = (input: unknown) => T;
+/** One versioned implementation registered in a ComponentOnce registry. */
+export interface ComponentOnceDefinition<TImplementation = unknown, TProps = unknown, THostContext = unknown, TPayload = unknown> {
+    readonly manifest: ComponentOnceManifest;
+    readonly implementation: TImplementation;
+    readonly validateProps?: ComponentOnceValidator<TProps>;
+    readonly validatePayload?: ComponentOnceValidator<TPayload>;
+    /** Phantom host-context type carried for compile-time host/module compatibility. */
+    readonly __hostContext?: THostContext;
+}
+/** The broad definition type accepted by heterogeneous registries and adapters. */
+export type AnyComponentOnceDefinition = ComponentOnceDefinition<unknown, unknown, unknown, unknown>;
+/** Exact load identity that storage and transport adapters may extend with their own fields. */
+export interface ComponentOnceLoadDescriptor extends ComponentOnceExactReference {
+}
+/** Host-provided loader that maps an adapter descriptor to one typed definition. */
+export interface ComponentOnceLoader<TDefinition extends AnyComponentOnceDefinition = AnyComponentOnceDefinition, TDescriptor extends ComponentOnceLoadDescriptor = ComponentOnceLoadDescriptor> {
+    load(descriptor: TDescriptor): Promise<TDefinition>;
+}
+/** Conflict behavior used when an exact id and version is already registered. */
+export type ComponentOnceConflictStrategy = "throw" | "keep-existing" | "replace";
+/** Options applied while registering one exact component definition. */
+export interface ComponentOnceRegistrationOptions {
+    /** How to handle an occupied exact id and version. Defaults to `throw`. */
+    readonly onConflict?: ComponentOnceConflictStrategy;
+    /** Select the registered version as the explicit default for its id. */
+    readonly setAsDefault?: boolean;
+}
+/** A request for an exact version or for a host-configured default version. */
+export interface ComponentOnceResolveRequest {
+    readonly id: string;
+    /** Omit only when the host has explicitly configured a default for this id. */
+    readonly version?: string;
+}
+/** Base error for registry, loading, and compatibility contract failures. */
+export declare class ComponentOnceError extends Error {
+    constructor(message: string);
+}
+/** Thrown when an id or version is empty. */
+export declare class ComponentOnceInvalidReferenceError extends ComponentOnceError {
+    readonly reference: ComponentOnceExactReference;
+    constructor(reference: ComponentOnceExactReference);
+}
+/** Thrown when registration finds an existing definition at the same exact id and version. */
+export declare class ComponentOnceDuplicateVersionError extends ComponentOnceError {
+    readonly reference: ComponentOnceExactReference;
+    readonly existing: AnyComponentOnceDefinition;
+    readonly incoming: AnyComponentOnceDefinition;
+    constructor(existing: AnyComponentOnceDefinition, incoming: AnyComponentOnceDefinition);
+}
+/** Thrown when an exact component definition cannot be found. */
+export declare class ComponentOnceDefinitionNotFoundError extends ComponentOnceError {
+    readonly reference: ComponentOnceExactReference;
+    constructor(reference: ComponentOnceExactReference);
+}
+/** Thrown when unversioned resolution has no host-configured default. */
+export declare class ComponentOnceDefaultVersionNotConfiguredError extends ComponentOnceError {
+    readonly id: string;
+    constructor(id: string);
+}
+/** Thrown when a loader returns a definition other than the exact descriptor requested. */
+export declare class ComponentOnceLoadedDefinitionMismatchError extends ComponentOnceError {
+    readonly requested: ComponentOnceExactReference;
+    readonly loaded: ComponentOnceExactReference;
+    constructor(requested: ComponentOnceExactReference, loaded: ComponentOnceExactReference);
+}
+/** Thrown when a component requires a capability the host did not provide. */
+export declare class ComponentOnceCapabilityMissingError extends ComponentOnceError {
+    readonly requirement: ComponentOnceRequirement;
+    constructor(requirement: ComponentOnceRequirement);
+}
+/** Thrown when a named host capability exists but its version is incompatible. */
+export declare class ComponentOnceCapabilityVersionError extends ComponentOnceError {
+    readonly requirement: ComponentOnceRequirement;
+    readonly available: ComponentOnceCapability;
+    constructor(requirement: ComponentOnceRequirement, available: ComponentOnceCapability);
+}
+/** Host-supplied compatibility rule for one named requirement and matching available capability. */
+export type ComponentOnceCapabilityCompatibility = (requirement: ComponentOnceRequirement, available: ComponentOnceCapability) => boolean;
+/** Compare one requirement and capability by exact name and version equality. */
+export declare function exactComponentOnceCapabilityCompatibility(requirement: ComponentOnceRequirement, available: ComponentOnceCapability): boolean;
+/** Find the host capability with the exact name required by one component requirement. */
+export declare function findComponentOnceCapability(requirement: ComponentOnceRequirement, available: readonly ComponentOnceCapability[]): ComponentOnceCapability | undefined;
+/** Check whether every manifest requirement is satisfied by host capabilities. */
+export declare function isComponentOnceCompatible(manifest: ComponentOnceManifest, available: readonly ComponentOnceCapability[], isCompatible?: ComponentOnceCapabilityCompatibility): boolean;
+/** Assert every manifest requirement before executing or mounting its implementation. */
+export declare function assertComponentOnceCompatible(manifest: ComponentOnceManifest, available: readonly ComponentOnceCapability[], isCompatible?: ComponentOnceCapabilityCompatibility): void;
+/** An isolated, storage-agnostic registry of exact component definitions. */
+export declare class ComponentOnceRegistry<TDefinition extends AnyComponentOnceDefinition = AnyComponentOnceDefinition> {
+    #private;
+    /** Register one definition without choosing a version implicitly. */
+    register(definition: TDefinition, options?: ComponentOnceRegistrationOptions): TDefinition;
+    /** Return an exact definition when present without applying a default. */
+    findExact(id: string, version: string): TDefinition | undefined;
+    /** Return an exact definition or throw when it is absent. */
+    getExact(id: string, version: string): TDefinition;
+    /** Report whether an exact id and version is registered. */
+    hasExact(id: string, version: string): boolean;
+    /** Resolve an exact version, or an explicitly configured default when version is omitted. */
+    resolve(request: ComponentOnceResolveRequest): TDefinition;
+    /** Configure one already registered exact version as the default for its id. */
+    setDefaultVersion(id: string, version: string): void;
+    /** Return the configured default version for an id when present. */
+    getDefaultVersion(id: string): string | undefined;
+    /** Remove the configured default selection for an id. */
+    clearDefaultVersion(id: string): boolean;
+    /** Remove and return one exact definition, also clearing a matching default. */
+    unregister(id: string, version: string): TDefinition | undefined;
+    /** List registered versions for an id in deterministic lexical order. */
+    listVersions(id: string): readonly string[];
+}
+/** Load one exact definition, verify its identity, and register it in an isolated registry. */
+export declare function loadAndRegisterComponentOnce<TDefinition extends AnyComponentOnceDefinition, TDescriptor extends ComponentOnceLoadDescriptor>(registry: ComponentOnceRegistry<TDefinition>, loader: ComponentOnceLoader<TDefinition, TDescriptor>, descriptor: TDescriptor, options?: ComponentOnceRegistrationOptions): Promise<TDefinition>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,217 @@
+/** Base error for registry, loading, and compatibility contract failures. */
+export class ComponentOnceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Thrown when an id or version is empty. */
+export class ComponentOnceInvalidReferenceError extends ComponentOnceError {
+    reference;
+    constructor(reference) {
+        super("Component ids and versions must be non-empty strings.");
+        this.reference = reference;
+    }
+}
+/** Thrown when registration finds an existing definition at the same exact id and version. */
+export class ComponentOnceDuplicateVersionError extends ComponentOnceError {
+    reference;
+    existing;
+    incoming;
+    constructor(existing, incoming) {
+        const { id, version } = incoming.manifest;
+        super(`Component "${id}" version "${version}" is already registered.`);
+        this.reference = { id, version };
+        this.existing = existing;
+        this.incoming = incoming;
+    }
+}
+/** Thrown when an exact component definition cannot be found. */
+export class ComponentOnceDefinitionNotFoundError extends ComponentOnceError {
+    reference;
+    constructor(reference) {
+        super(`Component "${reference.id}" version "${reference.version}" is not registered.`);
+        this.reference = reference;
+    }
+}
+/** Thrown when unversioned resolution has no host-configured default. */
+export class ComponentOnceDefaultVersionNotConfiguredError extends ComponentOnceError {
+    id;
+    constructor(id) {
+        super(`Component "${id}" has no configured default version.`);
+        this.id = id;
+    }
+}
+/** Thrown when a loader returns a definition other than the exact descriptor requested. */
+export class ComponentOnceLoadedDefinitionMismatchError extends ComponentOnceError {
+    requested;
+    loaded;
+    constructor(requested, loaded) {
+        super(`Loader returned component "${loaded.id}" version "${loaded.version}" while ` +
+            `"${requested.id}" version "${requested.version}" was requested.`);
+        this.requested = requested;
+        this.loaded = loaded;
+    }
+}
+/** Thrown when a component requires a capability the host did not provide. */
+export class ComponentOnceCapabilityMissingError extends ComponentOnceError {
+    requirement;
+    constructor(requirement) {
+        super("Component requires capability \"" + requirement.name + "\" version \"" +
+            requirement.version + "\", but the host did not provide that capability.");
+        this.requirement = requirement;
+    }
+}
+/** Thrown when a named host capability exists but its version is incompatible. */
+export class ComponentOnceCapabilityVersionError extends ComponentOnceError {
+    requirement;
+    available;
+    constructor(requirement, available) {
+        super("Component requires capability \"" + requirement.name + "\" version \"" +
+            requirement.version + "\", but the host provides version \"" +
+            available.version + "\".");
+        this.requirement = requirement;
+        this.available = available;
+    }
+}
+/** Compare one requirement and capability by exact name and version equality. */
+export function exactComponentOnceCapabilityCompatibility(requirement, available) {
+    return requirement.name === available.name && requirement.version === available.version;
+}
+/** Find the host capability with the exact name required by one component requirement. */
+export function findComponentOnceCapability(requirement, available) {
+    for (const capability of available) {
+        if (capability.name === requirement.name)
+            return capability;
+    }
+    return undefined;
+}
+/** Check whether every manifest requirement is satisfied by host capabilities. */
+export function isComponentOnceCompatible(manifest, available, isCompatible = exactComponentOnceCapabilityCompatibility) {
+    for (const requirement of manifest.requirements ?? []) {
+        const capability = findComponentOnceCapability(requirement, available);
+        if (capability === undefined || !isCompatible(requirement, capability))
+            return false;
+    }
+    return true;
+}
+/** Assert every manifest requirement before executing or mounting its implementation. */
+export function assertComponentOnceCompatible(manifest, available, isCompatible = exactComponentOnceCapabilityCompatibility) {
+    for (const requirement of manifest.requirements ?? []) {
+        const capability = findComponentOnceCapability(requirement, available);
+        if (capability === undefined) {
+            throw new ComponentOnceCapabilityMissingError(requirement);
+        }
+        if (!isCompatible(requirement, capability)) {
+            throw new ComponentOnceCapabilityVersionError(requirement, capability);
+        }
+    }
+}
+/** An isolated, storage-agnostic registry of exact component definitions. */
+export class ComponentOnceRegistry {
+    #definitions = new Map();
+    #defaultVersions = new Map();
+    /** Register one definition without choosing a version implicitly. */
+    register(definition, options = {}) {
+        assertValidReference(definition.manifest);
+        const { id, version } = definition.manifest;
+        let versions = this.#definitions.get(id);
+        if (versions === undefined) {
+            versions = new Map();
+            this.#definitions.set(id, versions);
+        }
+        const existing = versions.get(version);
+        let registered = definition;
+        if (existing !== undefined) {
+            switch (options.onConflict ?? "throw") {
+                case "throw":
+                    throw new ComponentOnceDuplicateVersionError(existing, definition);
+                case "keep-existing":
+                    registered = existing;
+                    break;
+                case "replace":
+                    versions.set(version, definition);
+                    break;
+            }
+        }
+        else {
+            versions.set(version, definition);
+        }
+        if (options.setAsDefault === true)
+            this.#defaultVersions.set(id, version);
+        return registered;
+    }
+    /** Return an exact definition when present without applying a default. */
+    findExact(id, version) {
+        return this.#definitions.get(id)?.get(version);
+    }
+    /** Return an exact definition or throw when it is absent. */
+    getExact(id, version) {
+        assertValidReference({ id, version });
+        const definition = this.findExact(id, version);
+        if (definition === undefined) {
+            throw new ComponentOnceDefinitionNotFoundError({ id, version });
+        }
+        return definition;
+    }
+    /** Report whether an exact id and version is registered. */
+    hasExact(id, version) {
+        return this.findExact(id, version) !== undefined;
+    }
+    /** Resolve an exact version, or an explicitly configured default when version is omitted. */
+    resolve(request) {
+        if (request.version !== undefined)
+            return this.getExact(request.id, request.version);
+        const version = this.#defaultVersions.get(request.id);
+        if (version === undefined) {
+            throw new ComponentOnceDefaultVersionNotConfiguredError(request.id);
+        }
+        return this.getExact(request.id, version);
+    }
+    /** Configure one already registered exact version as the default for its id. */
+    setDefaultVersion(id, version) {
+        this.getExact(id, version);
+        this.#defaultVersions.set(id, version);
+    }
+    /** Return the configured default version for an id when present. */
+    getDefaultVersion(id) {
+        return this.#defaultVersions.get(id);
+    }
+    /** Remove the configured default selection for an id. */
+    clearDefaultVersion(id) {
+        return this.#defaultVersions.delete(id);
+    }
+    /** Remove and return one exact definition, also clearing a matching default. */
+    unregister(id, version) {
+        const versions = this.#definitions.get(id);
+        const definition = versions?.get(version);
+        if (versions === undefined || definition === undefined)
+            return undefined;
+        versions.delete(version);
+        if (versions.size === 0)
+            this.#definitions.delete(id);
+        if (this.#defaultVersions.get(id) === version)
+            this.#defaultVersions.delete(id);
+        return definition;
+    }
+    /** List registered versions for an id in deterministic lexical order. */
+    listVersions(id) {
+        return [...(this.#definitions.get(id)?.keys() ?? [])].sort();
+    }
+}
+/** Load one exact definition, verify its identity, and register it in an isolated registry. */
+export async function loadAndRegisterComponentOnce(registry, loader, descriptor, options = {}) {
+    assertValidReference(descriptor);
+    const definition = await loader.load(descriptor);
+    const { id, version } = definition.manifest;
+    if (id !== descriptor.id || version !== descriptor.version) {
+        throw new ComponentOnceLoadedDefinitionMismatchError(descriptor, { id, version });
+    }
+    return registry.register(definition, options);
+}
+function assertValidReference(reference) {
+    if (reference.id.trim() === "" || reference.version.trim() === "") {
+        throw new ComponentOnceInvalidReferenceError(reference);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@componentonce/core",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.5"
+  },
+  "description": "Renderer-agnostic registry, versioning, loading, validation, and capability contracts for trusted dynamic components.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}