@syncbridge/common 0.13.8 → 0.14.0

package/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "0.13.8";
+export declare const version = "0.14.0";
 export declare const CLASS_METADATA: unique symbol;
 export declare const CLASS_TYPE: unique symbol;
 export declare const VARIABLE_CONTAINER: unique symbol;

package/constants.js

@@ -1,4 +1,4 @@
-export const version = '0.13.8';
+export const version = '0.14.0';
 export const CLASS_METADATA = Symbol.for('CLASS_METADATA');
 export const CLASS_TYPE = Symbol.for('CLASS_TYPE');
 export const VARIABLE_CONTAINER = Symbol.for('VARIABLE_CONTAINER');

package/decorators/component.decorator.js

@@ -33,7 +33,9 @@ export function Component(options) {
             throw new TypeError('Class name is required');
         /** Determine uri */
         Reflect.defineMetadata(CLASS_TYPE, 'component', target);
-        const packageName = pkgjson.name;
+        /* As in @Processor: a package published under another name (the npm
+         * mirror's @sbext/vendor__name) keeps its registry name here */
+        const packageName = pkgjson.syncbridge?.name || pkgjson.name;
         const uri = packageName + ':' + className;
         const metadata = defineOwnMetadata(target, CLASS_METADATA, {
             classType: 'component',

package/index.d.ts

@@ -17,8 +17,10 @@ export * from './models-document.js';
 export * from './processor-factory.js';
 export * from './registry/extension-package.js';
 export * from './registry/extension-registry.js';
+export * from './registry/package-manifest.js';
 export * from './utils/decode-profile.js';
 export * from './utils/materialize-metadata.js';
 export * from './utils/normalize-metadata.js';
+export * from './utils/registry-names.js';
 export * from './utils/type-guards.js';
 export * from './utils/uri-to-id.js';

package/index.js

@@ -17,8 +17,10 @@ export * from './models-document.js';
 export * from './processor-factory.js';
 export * from './registry/extension-package.js';
 export * from './registry/extension-registry.js';
+export * from './registry/package-manifest.js';
 export * from './utils/decode-profile.js';
 export * from './utils/materialize-metadata.js';
 export * from './utils/normalize-metadata.js';
+export * from './utils/registry-names.js';
 export * from './utils/type-guards.js';
 export * from './utils/uri-to-id.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncbridge/common",
-  "version": "0.13.8",
+  "version": "0.14.0",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
   "license": "MIT",

package/registry/extension-package.d.ts

@@ -4,6 +4,7 @@ import { BaseElement } from '../classes/base-element.js';
 import { ComponentBase } from '../classes/component-base.js';
 import { ProcessorBase } from '../classes/processor-base.js';
 import { ComponentMetadata, ElementMetadata, ProcessorMetadata } from '../models/index.js';
+import { type ExtensionPackageJson } from './package-manifest.js';
 /**
  *
  */
@@ -13,9 +14,19 @@ export declare class ExtensionPackage {
     description: string;
     path: string;
     entryPoint: string;
+    /** See `getManifestVersion`; `undefined` for a class registered directly */
+    manifestVersion?: number;
+    /** Registry packages this one depends on: registry name -> semver range */
+    registryDependencies: Record<string, string>;
+    /** What the package expects the host to provide */
+    peerDependencies: Record<string, string>;
     components: ComponentExtension[];
     processors: ProcessorExtension[];
     errors: Error[];
+    /**
+     * Takes the package's identity and dependencies from its `package.json`.
+     */
+    assignManifest(pkgJson: ExtensionPackageJson): void;
 }
 /**
  *

package/registry/extension-package.js

@@ -5,13 +5,29 @@ import { ProcessorBase } from '../classes/processor-base.js';
 import { SbError } from '../classes/sb-error.js';
 import { ComponentMetadata, ElementMetadata, ProcessorMetadata, } from '../models/index.js';
 import { isComponentBase, isProcessorBase } from '../utils/type-guards.js';
+import { getManifestVersion, } from './package-manifest.js';
 /**
  *
  */
 export class ExtensionPackage {
+    /** Registry packages this one depends on: registry name -> semver range */
+    registryDependencies = {};
+    /** What the package expects the host to provide */
+    peerDependencies = {};
     components = [];
     processors = [];
     errors = [];
+    /**
+     * Takes the package's identity and dependencies from its `package.json`.
+     */
+    assignManifest(pkgJson) {
+        this.name = pkgJson.syncbridge?.name || pkgJson.name;
+        this.version = pkgJson.version;
+        this.description = pkgJson.description;
+        this.manifestVersion = getManifestVersion(pkgJson);
+        this.registryDependencies = { ...pkgJson.syncbridge?.dependencies };
+        this.peerDependencies = { ...pkgJson.peerDependencies };
+    }
 }
 /**
  *

package/registry/extension-registry.js

@@ -138,9 +138,7 @@ export class ExtensionRegistry extends AsyncEventEmitter {
             entryPoint = pathToFileURL(entryPoint).href;
         }
         const pkg = new ExtensionPackage();
-        pkg.name = pkgJson.syncbridge?.name || pkgJson.name;
-        pkg.version = pkgJson.version;
-        pkg.description = pkgJson.description;
+        pkg.assignManifest(pkgJson);
         pkg.path = pkgDir;
         pkg.entryPoint = entryPoint;
         const module = await import(entryPoint);

package/registry/package-manifest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The manifest version a package built today carries. Version 1 is the
+ * bundled layout, version 2 the unbundled one with registry dependencies.
+ */
+export declare const MANIFEST_VERSION = 2;
+/**
+ * The `syncbridge` field of an extension package's `package.json`.
+ */
+export interface SyncBridgeManifest {
+    /** The name the package registers under, when it differs from `name` */
+    name?: string;
+    /** The version of the package contract - see `getManifestVersion` */
+    manifestVersion?: number;
+    /**
+     * @deprecated Written by syncbuild before `manifestVersion` existed and
+     * derived from syncbuild's own major version, so it describes the builder
+     * rather than the package. Read only as "manifest version 1".
+     */
+    version?: string;
+    /** Registry packages this one depends on: registry name -> semver range */
+    dependencies?: Record<string, string>;
+    components?: string[];
+    processors?: string[];
+}
+/**
+ * The parts of an extension package's `package.json` SyncBridge reads.
+ */
+export interface ExtensionPackageJson {
+    name: string;
+    version: string;
+    description?: string;
+    main?: string;
+    module?: string;
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    syncbridge?: SyncBridgeManifest;
+}
+/**
+ * Returns the manifest version of an extension package, or `undefined` when
+ * the `package.json` has no `syncbridge` field and is not one.
+ *
+ * A manifest without `manifestVersion` is version 1, whatever its legacy
+ * `version` says: that field followed syncbuild's major version, so reading
+ * it as a contract version would make a new syncbuild major look like a new
+ * package layout.
+ */
+export declare function getManifestVersion(pkgJson: Pick<ExtensionPackageJson, 'syncbridge'> | undefined): number | undefined;

package/registry/package-manifest.js

@@ -0,0 +1,27 @@
+import { SbError } from '../classes/sb-error.js';
+/**
+ * The manifest version a package built today carries. Version 1 is the
+ * bundled layout, version 2 the unbundled one with registry dependencies.
+ */
+export const MANIFEST_VERSION = 2;
+/**
+ * Returns the manifest version of an extension package, or `undefined` when
+ * the `package.json` has no `syncbridge` field and is not one.
+ *
+ * A manifest without `manifestVersion` is version 1, whatever its legacy
+ * `version` says: that field followed syncbuild's major version, so reading
+ * it as a contract version would make a new syncbuild major look like a new
+ * package layout.
+ */
+export function getManifestVersion(pkgJson) {
+    const manifest = pkgJson?.syncbridge;
+    if (!manifest || typeof manifest !== 'object')
+        return;
+    const v = manifest.manifestVersion;
+    if (v === undefined)
+        return 1;
+    if (!Number.isInteger(v) || v < 1) {
+        throw new SbError(`Invalid syncbridge.manifestVersion (${JSON.stringify(v)}), it must be a positive integer`);
+    }
+    return v;
+}

package/utils/materialize-metadata.js

@@ -29,7 +29,7 @@ export function materializeMetadata(profile, options) {
  */
 export function materializeMetadataSilent(profile, options) {
     const stackExecutor = new StackExecutor();
-    const processorRec = ExtensionRegistry.getProcessor(profile.processorUri);
+    const processorRec = ExtensionRegistry.getProcessor(profile.processorUri, profile.processorVersion);
     const metadata = omitUndefined(clone({
         classType: processorRec.metadata.classType,
         className: processorRec.metadata.className,

package/utils/registry-names.d.ts

@@ -0,0 +1,48 @@
+/** Prefix that marks a registry package in an import specifier */
+export declare const SB_SPECIFIER_PREFIX = "sb:";
+/**
+ * The npm scope registry packages are published under for development and
+ * tests: `@abisena/iomt` becomes `@sbext/abisena__iomt`. Reserved, so no
+ * registry organization can take it.
+ */
+export declare const SBEXT_SCOPE = "sbext";
+/**
+ * Organization names the registry does not let anyone create. A policy for
+ * creating organizations, not a naming rule: `syncbridge` is reserved for its
+ * owner, while `@syncbridge/sqb` is still a valid registry name.
+ */
+export declare const RESERVED_SCOPES: readonly string[];
+/**
+ * Checks a registry organization name - the scope, with or without its `@`.
+ * Returns the problems found; an empty array means it is valid.
+ *
+ * `__` is refused because `toSbextName` joins the scope and the name with
+ * it: a scope containing one could not be split back apart.
+ */
+export declare function validateScopeName(scope: string): string[];
+/**
+ * Checks a registry package name. Registry names are scoped (`@vendor/name`)
+ * and follow npm's naming rules, and neither part may contain `__`.
+ * Returns the problems found; an empty array means it is valid.
+ */
+export declare function validateRegistryName(name: string): string[];
+/**
+ * Maps a registry name to the npm name it is published under:
+ * `@abisena/iomt` -> `@sbext/abisena__iomt`.
+ */
+export declare function toSbextName(name: string): string;
+/**
+ * Maps an npm name under `@sbext` back to its registry name:
+ * `@sbext/abisena__iomt` -> `@abisena/iomt`.
+ */
+export declare function fromSbextName(npmName: string): string;
+/**
+ * Parses an import specifier that names a registry package:
+ * `sb:@abisena/iomt/protocol` -> `{ name: '@abisena/iomt', subpath: './protocol' }`.
+ * Returns `undefined` for a specifier without the `sb:` prefix, and throws for
+ * one that has it but does not name a valid registry package.
+ */
+export declare function parseSbSpecifier(specifier: string): {
+    name: string;
+    subpath: string;
+} | undefined;

package/utils/registry-names.js

@@ -0,0 +1,108 @@
+import { SbError } from '../classes/sb-error.js';
+/** Prefix that marks a registry package in an import specifier */
+export const SB_SPECIFIER_PREFIX = 'sb:';
+/**
+ * The npm scope registry packages are published under for development and
+ * tests: `@abisena/iomt` becomes `@sbext/abisena__iomt`. Reserved, so no
+ * registry organization can take it.
+ */
+export const SBEXT_SCOPE = 'sbext';
+/**
+ * Organization names the registry does not let anyone create. A policy for
+ * creating organizations, not a naming rule: `syncbridge` is reserved for its
+ * owner, while `@syncbridge/sqb` is still a valid registry name.
+ */
+export const RESERVED_SCOPES = [SBEXT_SCOPE, 'syncbridge'];
+/** npm's limit on the length of a whole package name, scope included */
+const MAX_NAME_LENGTH = 214;
+/** Lower-case, URL-safe, and not starting with `.` or `_` */
+const NAME_PART_PATTERN = /^[a-z0-9-][a-z0-9._-]*$/;
+/**
+ * Checks a registry organization name - the scope, with or without its `@`.
+ * Returns the problems found; an empty array means it is valid.
+ *
+ * `__` is refused because `toSbextName` joins the scope and the name with
+ * it: a scope containing one could not be split back apart.
+ */
+export function validateScopeName(scope) {
+    const s = scope.startsWith('@') ? scope.slice(1) : scope;
+    if (!s)
+        return ['Scope must not be empty'];
+    const problems = [];
+    if (!NAME_PART_PATTERN.test(s))
+        problems.push(`Scope "${s}" may only contain lower-case letters, digits, "-", "." and "_", and must not start with "." or "_"`);
+    if (s.includes('__'))
+        problems.push(`Scope "${s}" must not contain "__"`);
+    /* Unlike the other reserved scopes, this one can never be a vendor's */
+    if (s === SBEXT_SCOPE)
+        problems.push(`Scope "${s}" is reserved for the npm mirror`);
+    return problems;
+}
+/**
+ * Checks a registry package name. Registry names are scoped (`@vendor/name`)
+ * and follow npm's naming rules, and neither part may contain `__`.
+ * Returns the problems found; an empty array means it is valid.
+ */
+export function validateRegistryName(name) {
+    const m = /^@([^/]*)\/([^/]*)$/.exec(name);
+    if (!m)
+        return [`"${name}" must be a scoped name, "@vendor/name"`];
+    const [, scope, pkg] = m;
+    const problems = validateScopeName(scope);
+    if (!pkg)
+        problems.push(`"${name}" has no name after the scope`);
+    else {
+        if (!NAME_PART_PATTERN.test(pkg))
+            problems.push(`Name "${pkg}" may only contain lower-case letters, digits, "-", "." and "_", and must not start with "." or "_"`);
+        if (pkg.includes('__'))
+            problems.push(`Name "${pkg}" must not contain "__"`);
+    }
+    if (name.length > MAX_NAME_LENGTH)
+        problems.push(`"${name}" is longer than ${MAX_NAME_LENGTH} characters`);
+    return problems;
+}
+function assertRegistryName(name) {
+    const problems = validateRegistryName(name);
+    if (problems.length)
+        throw new SbError(`Invalid registry name. ${problems.join('. ')}`);
+}
+/**
+ * Maps a registry name to the npm name it is published under:
+ * `@abisena/iomt` -> `@sbext/abisena__iomt`.
+ */
+export function toSbextName(name) {
+    assertRegistryName(name);
+    const [scope, pkg] = name.slice(1).split('/');
+    return `@${SBEXT_SCOPE}/${scope}__${pkg}`;
+}
+/**
+ * Maps an npm name under `@sbext` back to its registry name:
+ * `@sbext/abisena__iomt` -> `@abisena/iomt`.
+ */
+export function fromSbextName(npmName) {
+    const prefix = `@${SBEXT_SCOPE}/`;
+    if (!npmName.startsWith(prefix))
+        throw new SbError(`"${npmName}" is not under the @${SBEXT_SCOPE} scope`);
+    const parts = npmName.slice(prefix.length).split('__');
+    if (parts.length !== 2)
+        throw new SbError(`"${npmName}" is not a "@${SBEXT_SCOPE}/<vendor>__<name>" name`);
+    const name = `@${parts[0]}/${parts[1]}`;
+    assertRegistryName(name);
+    return name;
+}
+/**
+ * Parses an import specifier that names a registry package:
+ * `sb:@abisena/iomt/protocol` -> `{ name: '@abisena/iomt', subpath: './protocol' }`.
+ * Returns `undefined` for a specifier without the `sb:` prefix, and throws for
+ * one that has it but does not name a valid registry package.
+ */
+export function parseSbSpecifier(specifier) {
+    if (!specifier.startsWith(SB_SPECIFIER_PREFIX))
+        return;
+    const rest = specifier.slice(SB_SPECIFIER_PREFIX.length);
+    const m = /^(@[^/]+\/[^/]+)(\/.*)?$/.exec(rest);
+    if (!m)
+        throw new SbError(`"${specifier}" must name a registry package, "sb:@vendor/name"`);
+    assertRegistryName(m[1]);
+    return { name: m[1], subpath: m[2] ? '.' + m[2] : '.' };
+}