@k8ts/metadata 0.7.3 → 0.10.0

package/dist/meta.d.ts

@@ -1,8 +1,7 @@
 import type { InputMeta, MetaInputParts } from "./input/dict-input";
-import { ValueKey } from "./key/repr";
+import { MetadataKey } from "./key/repr";
 import { Key } from "./key/types";
 export type Meta = Meta.Meta;
-export type MutableMeta = Meta.MutableMeta;
 declare const MetaMarker: unique symbol;
 export interface MetaLike {
     readonly [MetaMarker]: true;
@@ -11,56 +10,291 @@ export declare namespace Meta {
     function _checkNameValue(what: string, v: string): void;
     function _checkValue(key: string, v: string): void;
     type Input = InputMeta;
-    class Meta implements Iterable<[ValueKey, string]>, MetaLike {
+    /**
+     * Mutable storage for k8s metadata. K8s metadata includes labels, annotations, and core fields.
+     * These are addressed using `CharPrefix`.
+     *
+     * - **Labels**: `%key` → `metadata.labels.key`
+     * - **Annotations**: `^key` → `metadata.annotations.key`
+     * - **Comments**: `#key` → Build-time metadata, not manifested in k8s objects.
+     * - **Core metadata**: `key` → `metadata.key` (e.g., `name`, `namespace`, etc.)
+     *
+     * In addition, you can address different metadata keys under the same domain using a
+     * `DomainKey`, of the form `example.com/`. When using a `DomainKey`, you use a `CharPrefix` on
+     * the inner keys.
+     *
+     * This lets you add different kinds of metadata under the same domain with ease.
+     *
+     * @example
+     *     meta.add("%app", "my-app") // adds label 'app' with value 'my-app'
+     *     meta.add("example.section/", {
+     *         "%label1": "value1", // adds `%example.section/label1` with value 'value1'
+     *         "^annotation1": "value2" // adds `^example.section/annotation1` with value 'value2'
+     *     })
+     */
+    class Meta implements Iterable<[MetadataKey, string]>, MetaLike {
         private readonly _dict;
         readonly [MetaMarker] = true;
+        /**
+         * Constructs a new Meta instance from a map of key-value pairs. Validates all keys and
+         * values during construction.
+         *
+         * @param _dict Internal map storing metadata key-value pairs
+         * @throws {MetadataError} If any key or value is invalid
+         */
         constructor(_dict: Map<string, string>);
-        [Symbol.iterator](): Generator<[ValueKey, string], void, unknown>;
+        /**
+         * Makes Meta instances iterable, yielding [ValueKey, string] pairs.
+         *
+         * @example
+         *     for (const [key, value] of meta) {
+         *         console.log(key.str, value)
+         *     }
+         */
+        [Symbol.iterator](): Generator<[MetadataKey, string], void, unknown>;
         protected _create(raw: Map<string, string>): Meta;
+        /**
+         * Creates a deep clone of this object.
+         *
+         * @returns
+         */
         clone(): Meta;
+        /**
+         * Deletes a single value key from the metadata.
+         *
+         * @example
+         *     meta.delete("name") // deletes core metadata 'name'
+         *     meta.delete("%app") // deletes label 'app'
+         *
+         * @param key The value key to delete
+         */
         delete(key: Key.Value): Meta;
-        delete(ns: Key.Section, key: string): Meta;
-        delete(ns: Key.Section): Meta;
+        /**
+         * Deletes specific keys under a domain prefix.
+         *
+         * @example
+         *     meta.delete("example.com/", "key1", "key2") // deletes specific keys in section
+         *
+         * @param ns The section key namespace
+         * @param keys Specific value keys within the section to delete
+         */
+        delete(ns: Key.Domain, ...keys: Key.Value[]): Meta;
+        /**
+         * Deletes all keys within a section namespace.
+         *
+         * @example
+         *     meta.delete("example.com/") // deletes all keys in section
+         *
+         * @param ns The section key namespace to delete
+         */
+        delete(ns: Key.Domain): Meta;
+        /**
+         * Adds a single key-value pair to the metadata. Throws if the key already exists.
+         *
+         * @example
+         *     meta.add("%app", "my-app") // adds label
+         *     meta.add("name", "my-resource") // adds core metadata
+         *
+         * @param key The value key to add
+         * @param value The value to associate with the key
+         */
         add(key: Key.Value, value?: string): Meta;
-        add(key: Key.Section, value: MetaInputParts.Nested): Meta;
+        /**
+         * Adds a nested object of key-value pairs within a section namespace. Throws if any key
+         * already exists.
+         *
+         * @example
+         *     meta.add("example.com/", { "%label": "value", "^annotation": "data" })
+         *
+         * @param key The section key namespace
+         * @param value Nested object containing key-value pairs
+         */
+        add(key: Key.Domain, value: MetaInputParts.Nested): Meta;
+        /**
+         * Adds multiple key-value pairs from an input object. Throws if any key already exists.
+         *
+         * @example
+         *     meta.add({ "%app": "my-app", name: "my-resource" })
+         *
+         * @param input Object or map containing key-value pairs to add
+         */
         add(input: InputMeta): Meta;
+        /**
+         * Compares this Meta instance to another for equality. Two instances are equal if they
+         * contain the same key-value pairs.
+         *
+         * @param other The other Meta instance or input to compare against
+         * @returns Whether the two Meta instances are equal
+         */
         equals(other: Meta.Input): boolean;
-        section(key: string): Map<string, string>;
+        /**
+         * Overwrites a single key-value pair, replacing any existing value.
+         *
+         * @example
+         *     meta.overwrite("%app", "new-app") // replaces existing label value
+         *
+         * @param key The value key to overwrite
+         * @param value The new value (undefined removes the key)
+         */
         overwrite(key: Key.Value, value: string | undefined): Meta;
-        overwrite(key: Key.Section, value: MetaInputParts.Nested): Meta;
+        /**
+         * Overwrites key-value pairs within a section namespace.
+         *
+         * @example
+         *     meta.overwrite("example.com/", { "%label": "new-value" })
+         *
+         * @param key The section key namespace
+         * @param value Nested object containing key-value pairs to overwrite
+         */
+        overwrite(key: Key.Domain, value: MetaInputParts.Nested): Meta;
+        /**
+         * Overwrites multiple key-value pairs from an input object.
+         *
+         * @example
+         *     meta.overwrite({ "%app": "new-app", name: "new-name" })
+         *
+         * @param input Object or map containing key-value pairs to overwrite
+         */
         overwrite(input?: InputMeta): Meta;
-        has<X extends Key.Value>(key: X): boolean;
+        /**
+         * Checks if a key with a given domain prefix exists in the metadata.
+         *
+         * @example
+         *     meta.has("example.com/") // Checks for any key with this domain
+         *     meta.has("%app") // Checks for the label 'app'
+         *
+         * @param domainPrefix The domain prefix to check for
+         * @returns True if any keys exist under the specified domain prefix, false otherwise
+         */
+        has(domainPrefix: Key.Domain): boolean;
+        /** @param key */
+        has(key: Key.Value): boolean;
+        /**
+         * Retrieves the value for the specified key. Throws if the key doesn't exist.
+         *
+         * @example
+         *     const appName = meta.get("%app")
+         *
+         * @param key The value key to retrieve
+         * @returns The value associated with the key
+         * @throws {MetadataError} If the key is not found
+         */
         get(key: Key.Value): string;
+        /**
+         * Attempts to retrieve the value for the specified key, returning a fallback if not found.
+         *
+         * @example
+         *     const appName = meta.tryGet("%app", "default-app")
+         *
+         * @param key The value key to retrieve
+         * @param fallback Optional fallback value if key doesn't exist
+         * @returns The value associated with the key, or the fallback value
+         * @throws {MetadataError} If a domain key is provided instead of a value key
+         */
         tryGet(key: Key.Value, fallback?: string): string | undefined;
-        private _matchSectionKeys;
-        pick(...keySpecs: Key.Key[]): Meta;
+        private _matchDomainPrefixes;
+        /**
+         * Creates a new Meta instance containing only some of the keys. You can pass both entire
+         * keys and domain prefixes to include all keys under that domain.
+         *
+         * @example
+         *     const subset = meta.pick("%app", "name", "example.com/")
+         *
+         * @param keySpecs Keys or domain prefixes to include in the result
+         * @returns A new Meta instance with only the picked keys
+         */
+        pick(...keySpecs: (Key.Domain | Key.Value)[]): Meta;
         private _prefixed;
+        /**
+         * Returns all labels as a plain object that can be embedded into a k8s manifest, with keys
+         * in canonical order.
+         *
+         * @example
+         *     const labels = Meta.make({
+         *         "%app": "my-app",
+         *         "%tier": "backend"
+         *     }).labels
+         *     // { app: "my-app", tier: "backend" }
+         */
         get labels(): Record<string, any>;
+        /**
+         * Returns all annotations as a plain object that can be embedded into a k8s manifest, with
+         * keys in canonical order.
+         *
+         * @example
+         *     const annotations = Meta.make({
+         *         "^note": "This is important",
+         *         "^description": "Detailed info"
+         *     }).annotations
+         *     // { note: "This is important", description: "Detailed info" }
+         */
         get annotations(): Record<string, any>;
+        /**
+         * Returns all comments (build-time metadata) as a plain object, with keys in canonical
+         * order.
+         *
+         * @example
+         *     const comments = Meta.make({
+         *         "#note": "Internal use only"
+         *     }).comments
+         *     // { note: "Internal use only" }
+         */
         get comments(): Record<string, any>;
+        /**
+         * Returns all core metadata fields (`name` and `namespace`) as a plain object that can be
+         * embedded into a k8s manifest, with keys in canonical order.
+         *
+         * @example
+         *     const core = meta.core // { name: "my-resource", namespace: "default" }
+         */
+        get core(): { [key in Key.Special]?: string; };
+        /**
+         * Returns all metadata key-value pairs as a flat JavaScript object, with each key prefixed
+         * appropriately.
+         *
+         * @example
+         *     const all = Meta.make({
+         *         "%app": "my-app",
+         *         "^note": "This is important",
+         *         name: "my-resource"
+         *     }).values
+         *     // { "%app": "my-app", "^note": "This is important", "name": "my-resource" }
+         */
         get values(): {
             [k: string]: string;
         };
-        get keys(): ValueKey[];
-        get core(): { [key in Key.Special]?: string; };
-        remove(key: Key.Value): this;
-        remove(ns: Key.Section, key: string): this;
-        remove(ns: Key.Section): this;
-        expand(): {
-            labels: Record<string, any>;
-            annotations: Record<string, any>;
-            namespace?: string | undefined;
-            name?: string | undefined;
-        };
+        private get _keys();
     }
+    /**
+     * Creates a Meta instance with a single key-value pair.
+     *
+     * @example
+     *     const meta = Meta.make("%app", "my-app")
+     *
+     * @param key The value key
+     * @param value The value to associate with the key
+     */
     function make(key: Key.Value, value: string): Meta;
-    function make(key: Key.Section, value: MetaInputParts.Nested): Meta;
+    /**
+     * Creates a Meta instance with key-value pairs within a section namespace.
+     *
+     * @example
+     *     const meta = Meta.make("example.com/", { "%label": "value" })
+     *
+     * @param key The section key namespace
+     * @param value Nested object containing key-value pairs
+     */
+    function make(key: Key.Domain, value: MetaInputParts.Nested): Meta;
+    /**
+     * Creates a Meta instance from an input object or returns an empty Meta if no input provided.
+     *
+     * @example
+     *     const meta = Meta.make({ "%app": "my-app", name: "resource" })
+     *     const empty = Meta.make()
+     *
+     * @param input Object or map containing key-value pairs
+     */
     function make(input?: InputMeta): Meta;
-    function splat(...input: InputMeta[]): Meta;
-    function is(value: any): value is Meta;
-    class MutableMeta extends Meta {
-        constructor(...args: any[]);
-    }
 }
 export {};
 //# sourceMappingURL=meta.d.ts.map

package/dist/meta.d.ts.map

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