import type { Pipeable } from "./Pipeable.ts";
import * as PrimaryKey from "./PrimaryKey.ts";
declare const TypeId: "~effect/HashRing";
/**
 * A weighted consistent-hashing ring for assigning inputs to nodes with stable
 * remapping as nodes are added or removed.
 *
 * **When to use**
 *
 * Use to maintain a mutable weighted hash ring for routing keys or shards to
 * nodes identified by `PrimaryKey`.
 *
 * **Details**
 *
 * Nodes are identified by their `PrimaryKey` value and can be iterated from the
 * ring.
 *
 * @stability unstable
 * @category models
 * @since 3.19.0
 */
export interface HashRing<A extends PrimaryKey.PrimaryKey> extends Pipeable, Iterable<A> {
    readonly [TypeId]: typeof TypeId;
    readonly baseWeight: number;
    totalWeightCache: number;
    readonly nodes: Map<string, [node: A, weight: number]>;
    ring: Array<[hash: number, node: string]>;
}
/**
 * Checks whether a value is a `HashRing`.
 *
 * **When to use**
 *
 * Use to narrow an `unknown` value before treating it as a `HashRing`, such as
 * values crossing an untyped boundary.
 *
 * **Details**
 *
 * The guard checks for the module's internal `TypeId` property and narrows to
 * `HashRing<any>`.
 *
 * **Gotchas**
 *
 * This is a structural type-id check; it does not validate the ring's `nodes`,
 * `ring`, or weight state.
 *
 * @see {@link HashRing} for the type narrowed by this guard
 * @see {@link make} for creating an empty `HashRing`
 *
 * @stability unstable
 * @category guards
 * @since 3.19.0
 */
export declare const isHashRing: (u: unknown) => u is HashRing<any>;
/**
 * Creates an empty `HashRing`.
 *
 * **When to use**
 *
 * Use to create an empty weighted consistent-hashing ring with the default or
 * custom virtual-point density.
 *
 * **Details**
 *
 * `baseWeight` controls how many virtual points are added for a node with
 * weight `1`; it defaults to `128` and is clamped to at least `1`.
 *
 * @see {@link add} for registering one node after creation
 * @see {@link addMany} for registering several nodes after creation
 *
 * @stability unstable
 * @category constructors
 * @since 3.19.0
 */
export declare const make: <A extends PrimaryKey.PrimaryKey>(options?: {
    readonly baseWeight?: number | undefined;
}) => HashRing<A>;
/**
 * Adds new nodes to the ring. If a node already exists in the ring, it
 * will be updated. For example, you can use this to update the node's weight.
 *
 * **When to use**
 *
 * Use to register or update several nodes in a `HashRing` at the same weight.
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const addMany: {
    /**
     * Adds new nodes to the ring. If a node already exists in the ring, it
     * will be updated. For example, you can use this to update the node's weight.
     *
     * **When to use**
     *
     * Use to register or update several nodes in a `HashRing` at the same weight.
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(nodes: Iterable<A>, options?: {
        readonly weight?: number | undefined;
    }): (self: HashRing<A>) => HashRing<A>;
    /**
     * Adds new nodes to the ring. If a node already exists in the ring, it
     * will be updated. For example, you can use this to update the node's weight.
     *
     * **When to use**
     *
     * Use to register or update several nodes in a `HashRing` at the same weight.
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, nodes: Iterable<A>, options?: {
        readonly weight?: number | undefined;
    }): HashRing<A>;
};
/**
 * Adds a new node to the ring. If the node already exists in the ring, it
 * will be updated. For example, you can use this to update the node's weight.
 *
 * **When to use**
 *
 * Use to register one node in a `HashRing` so lookups and shard assignments can
 * return it, or update that node's weight.
 *
 * **Details**
 *
 * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
 * clamped to at least `0.1`.
 *
 * **Gotchas**
 *
 * This mutates and returns the same ring instance.
 *
 * @see {@link addMany} for adding or updating several nodes
 * @see {@link remove} for unregistering a node
 * @see {@link has} for checking primary-key membership
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const add: {
    /**
     * Adds a new node to the ring. If the node already exists in the ring, it
     * will be updated. For example, you can use this to update the node's weight.
     *
     * **When to use**
     *
     * Use to register one node in a `HashRing` so lookups and shard assignments can
     * return it, or update that node's weight.
     *
     * **Details**
     *
     * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
     * clamped to at least `0.1`.
     *
     * **Gotchas**
     *
     * This mutates and returns the same ring instance.
     *
     * @see {@link addMany} for adding or updating several nodes
     * @see {@link remove} for unregistering a node
     * @see {@link has} for checking primary-key membership
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(node: A, options?: {
        readonly weight?: number | undefined;
    }): (self: HashRing<A>) => HashRing<A>;
    /**
     * Adds a new node to the ring. If the node already exists in the ring, it
     * will be updated. For example, you can use this to update the node's weight.
     *
     * **When to use**
     *
     * Use to register one node in a `HashRing` so lookups and shard assignments can
     * return it, or update that node's weight.
     *
     * **Details**
     *
     * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
     * clamped to at least `0.1`.
     *
     * **Gotchas**
     *
     * This mutates and returns the same ring instance.
     *
     * @see {@link addMany} for adding or updating several nodes
     * @see {@link remove} for unregistering a node
     * @see {@link has} for checking primary-key membership
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, node: A, options?: {
        readonly weight?: number | undefined;
    }): HashRing<A>;
};
/**
 * Removes the node from the ring. No-op's if the node does not exist.
 *
 * **When to use**
 *
 * Use to remove a node that has left the pool so future lookups and shard
 * assignments stop returning it.
 *
 * **Details**
 *
 * Removal matches by `PrimaryKey.value`, so any value with the same primary key
 * removes the same ring member.
 *
 * **Gotchas**
 *
 * This mutates and returns the same ring instance.
 *
 * @see {@link add} for registering or updating a node
 * @see {@link has} for checking membership by primary key
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const remove: {
    /**
     * Removes the node from the ring. No-op's if the node does not exist.
     *
     * **When to use**
     *
     * Use to remove a node that has left the pool so future lookups and shard
     * assignments stop returning it.
     *
     * **Details**
     *
     * Removal matches by `PrimaryKey.value`, so any value with the same primary key
     * removes the same ring member.
     *
     * **Gotchas**
     *
     * This mutates and returns the same ring instance.
     *
     * @see {@link add} for registering or updating a node
     * @see {@link has} for checking membership by primary key
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(node: A): (self: HashRing<A>) => HashRing<A>;
    /**
     * Removes the node from the ring. No-op's if the node does not exist.
     *
     * **When to use**
     *
     * Use to remove a node that has left the pool so future lookups and shard
     * assignments stop returning it.
     *
     * **Details**
     *
     * Removal matches by `PrimaryKey.value`, so any value with the same primary key
     * removes the same ring member.
     *
     * **Gotchas**
     *
     * This mutates and returns the same ring instance.
     *
     * @see {@link add} for registering or updating a node
     * @see {@link has} for checking membership by primary key
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, node: A): HashRing<A>;
};
/**
 * Checks whether the ring contains a node with the same `PrimaryKey` value.
 *
 * **When to use**
 *
 * Use when you need to know whether registering a node would update an existing
 * ring member because another node already has the same primary-key identity.
 *
 * **Details**
 *
 * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
 * matching is by primary key, not object identity or weight.
 *
 * @see {@link add} for registering or updating nodes
 * @see {@link remove} for removing nodes by the same primary-key identity
 * @see {@link get} for routing an input string to a node
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const has: {
    /**
     * Checks whether the ring contains a node with the same `PrimaryKey` value.
     *
     * **When to use**
     *
     * Use when you need to know whether registering a node would update an existing
     * ring member because another node already has the same primary-key identity.
     *
     * **Details**
     *
     * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
     * matching is by primary key, not object identity or weight.
     *
     * @see {@link add} for registering or updating nodes
     * @see {@link remove} for removing nodes by the same primary-key identity
     * @see {@link get} for routing an input string to a node
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(node: A): (self: HashRing<A>) => boolean;
    /**
     * Checks whether the ring contains a node with the same `PrimaryKey` value.
     *
     * **When to use**
     *
     * Use when you need to know whether registering a node would update an existing
     * ring member because another node already has the same primary-key identity.
     *
     * **Details**
     *
     * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
     * matching is by primary key, not object identity or weight.
     *
     * @see {@link add} for registering or updating nodes
     * @see {@link remove} for removing nodes by the same primary-key identity
     * @see {@link get} for routing an input string to a node
     *
     * @stability unstable
     * @category combinators
     * @since 3.19.0
     */
    <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, node: A): boolean;
};
/**
 * Gets the node which should handle the given input. Returns undefined if
 * the hashring has no elements with weight.
 *
 * **When to use**
 *
 * Use to route a single string input key to the current ring member responsible
 * for that key.
 *
 * @see {@link getShards} for assigning fixed shard indexes instead of routing
 * one input string at a time
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const get: <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, input: string) => A | undefined;
/**
 * Computes a balanced shard distribution across the nodes in the ring.
 *
 * **When to use**
 *
 * Use to precompute ownership for a fixed number of shard indexes across the
 * current ring members.
 *
 * **Details**
 *
 * Finite fractional values of `count` are rounded down. `NaN` and non-positive
 * values produce an empty shard distribution.
 *
 * @stability unstable
 * @category combinators
 * @since 3.19.0
 */
export declare const getShards: <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, count: number) => Array<A> | undefined;
export {};
//# sourceMappingURL=HashRing.d.ts.map