@k8ts/metadata/dist/meta.d.ts

K8ts tools for working with k8ts metadata.

import type { Metadata_Input, MetaInputParts } from "./input/dict-input";
import type { Metadata_Key_sDomain, Metadata_Key_sValue, NotPrefixed } from "./input/key/string-types";
/**
 * 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'
 *     })
 */
export declare class Metadata implements Iterable<[Metadata_Key_sValue, string]> {
    private readonly _dict;
    /**
     * Constructs a Metadata instance with a single key-value pair.
     *
     * @example
     *     const meta = new Metadata("%app", "my-app")
     *
     * @param key The value key
     * @param value The value to associate with the key
     */
    constructor(key: Metadata_Key_sValue, value: string);
    /**
     * Constructs a Metadata instance with key-value pairs within a section namespace.
     *
     * @example
     *     const meta = new Metadata("example.com/", { "%label": "value" })
     *
     * @param key The section key namespace
     * @param value Nested object containing key-value pairs
     */
    constructor(key: Metadata_Key_sDomain, value: MetaInputParts.Nested);
    /**
     * Constructs a Metadata instance from an input object or returns an empty Metadata if no input
     * provided.
     *
     * @example
     *     const meta = new Metadata({ "%app": "my-app", name: "resource" })
     *     const empty = new Metadata()
     *
     * @param input Object or map containing key-value pairs
     */
    constructor(input?: Metadata_Input);
    /**
     * Makes Metadata instances iterable, yielding [ValueKey, string] pairs.
     *
     * @example
     *     for (const [key, value] of meta) {
     *         console.log(key.str, value)
     *     }
     */
    [Symbol.iterator](): Generator<[`%${string}` | `^${string}` | `#${string}`, string], void, unknown>;
    /**
     * Creates a deep clone of this object.
     *
     * @returns
     */
    clone(): Metadata;
    /**
     * 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: Metadata_Key_sValue): Metadata;
    /**
     * 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: Metadata_Key_sDomain, keys: Metadata_Key_sValue[]): Metadata;
    /**
     * 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: Metadata_Key_sDomain): Metadata;
    /**
     * 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: Metadata_Key_sValue, value?: string): Metadata;
    /**
     * 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<Domain extends NotPrefixed<Domain>>(key: Domain, value: MetaInputParts.Nested): Metadata;
    /**
     * 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: Metadata_Input): Metadata;
    /**
     * Compares this Metadata instance to another for equality. Two instances are equal if they
     * contain the same key-value pairs.
     *
     * @param other The other Metadata instance or input to compare against
     * @returns Whether the two Metadata instances are equal
     */
    equals(other: Metadata_Input): boolean;
    /**
     * 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: Metadata_Key_sValue, value: string | undefined): Metadata;
    /**
     * 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<Domain extends NotPrefixed<Domain>>(key: Domain, value: MetaInputParts.Nested): Metadata;
    /**
     * 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?: Metadata_Input): Metadata;
    /**
     * 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<Domain extends NotPrefixed<Domain>>(domainPrefix: Domain): boolean;
    /** @param key */
    has(key: Metadata_Key_sValue): 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 {K8tsMetadataError} If the key is not found
     */
    get(key: Metadata_Key_sValue): 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 {K8tsMetadataError} If a domain key is provided instead of a value key
     */
    tryGet(key: Metadata_Key_sValue, fallback?: string): string | undefined;
    private get _parsedPairs();
    private _matchDomainPrefixes;
    /**
     * Creates a new Metadata 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 Metadata instance with only the picked keys
     */
    pick(...keySpecs: (Metadata_Key_sDomain | Metadata_Key_sValue)[]): Metadata;
    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 = Metadata.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 = Metadata.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 = Metadata.make({
     *         "#note": "Internal use only"
     *     }).comments
     *     // { note: "Internal use only" }
     */
    get comments(): Record<string, any>;
    /**
     * Returns all metadata key-value pairs as a flat JavaScript object, with each key prefixed
     * appropriately.
     *
     * @example
     *     const all = Metadata.make({
     *         "%app": "my-app",
     *         "^note": "This is important",
     *         name: "my-resource"
     *     }).values
     *     // { "%app": "my-app", "^note": "This is important", "name": "my-resource" }
     */
    get record(): {
        [k: string]: string;
    };
    private get _keys();
}
//# sourceMappingURL=meta.d.ts.map