.opencode/node_modules/effect/dist/unstable/cluster/Snowflake.d.ts

/**
 * Creates compact, sortable identifiers for cluster messages and runtime
 * events.
 *
 * A snowflake id is a branded `bigint` built from a millisecond timestamp, a
 * machine id, and a sequence number for that machine. The parts make generated
 * ids sortable by time while still being unique for a runner. This module
 * includes schemas for bigint and string encodings, helpers for creating and
 * reading ids, and a `Clock`-backed generator service for cluster runtime use.
 *
 * @since 4.0.0
 */
import type * as Brand from "../../Brand.ts";
import * as Context from "../../Context.ts";
import * as DateTime from "../../DateTime.ts";
import * as Effect from "../../Effect.ts";
import * as Layer from "../../Layer.ts";
import * as Schema from "../../Schema.ts";
import type { MachineId } from "./MachineId.ts";
/**
 * Runtime brand identifier for cluster snowflake ids.
 *
 * @category type IDs
 * @since 4.0.0
 */
export declare const TypeId = "~effect/cluster/Snowflake";
/**
 * Type-level representation of the cluster snowflake brand identifier.
 *
 * @category type IDs
 * @since 4.0.0
 */
export type TypeId = typeof TypeId;
/**
 * Branded bigint identifier composed from a timestamp, machine id, and per-machine
 * sequence number.
 *
 * @category models
 * @since 4.0.0
 */
export type Snowflake = Brand.Branded<bigint, TypeId>;
/**
 * Constructs a branded cluster snowflake id from a bigint or bigint-compatible
 * string.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const Snowflake: (input: string | bigint) => Snowflake;
/**
 * Namespace containing support types for snowflake parts and generators.
 *
 * @since 4.0.0
 */
export declare namespace Snowflake {
    /**
     * Decoded components of a snowflake id: Unix timestamp milliseconds, machine id,
     * and sequence number.
     *
     * @category models
     * @since 4.0.0
     */
    interface Parts {
        readonly timestamp: number;
        readonly machineId: MachineId;
        readonly sequence: number;
    }
    /**
     * Stateful generator for runner-local snowflake ids, exposing an unsafe
     * synchronous `nextUnsafe` operation and an effectful machine id setter.
     *
     * @category models
     * @since 4.0.0
     */
    interface Generator {
        readonly nextUnsafe: () => Snowflake;
        readonly setMachineId: (machineId: MachineId) => Effect.Effect<void>;
    }
}
/**
 * Schema type for snowflake ids represented as branded bigints.
 *
 * @category schemas
 * @since 4.0.0
 */
export interface SnowflakeFromBigInt extends Schema.brand<Schema.BigInt, TypeId> {
}
/**
 * Schema for snowflake ids represented as branded bigints.
 *
 * @category schemas
 * @since 4.0.0
 */
export declare const SnowflakeFromBigInt: SnowflakeFromBigInt;
/**
 * Schema type for snowflake ids decoded from strings into branded bigints.
 *
 * @category schemas
 * @since 4.0.0
 */
export interface SnowflakeFromString extends Schema.decodeTo<SnowflakeFromBigInt, Schema.String> {
}
/**
 * Schema that decodes snowflake ids from strings into branded bigints and encodes
 * them back to strings.
 *
 * @category schemas
 * @since 4.0.0
 */
export declare const SnowflakeFromString: SnowflakeFromString;
/**
 * Defines the custom snowflake epoch in Unix milliseconds.
 *
 * @category constants
 * @since 4.0.0
 */
export declare const constEpochMillis: number;
/**
 * Creates a branded snowflake id from a timestamp, machine id, and sequence number,
 * using the custom snowflake epoch and 10-bit machine id and 12-bit sequence
 * fields.
 *
 * **When to use**
 *
 * Use to pack known timestamp, machine id, and sequence parts into a branded
 * snowflake id.
 *
 * **Gotchas**
 *
 * Machine id values are encoded modulo 1024, and sequence values modulo 4096;
 * values outside those ranges wrap instead of being rejected.
 *
 * @see {@link toParts} for the inverse operation that decodes a snowflake id into timestamp, machine id, and sequence parts
 * @see {@link makeGenerator} for generating ids with Clock-backed timestamp and sequence management
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const make: (options: {
    readonly machineId: MachineId;
    readonly sequence: number;
    readonly timestamp: number;
}) => Snowflake;
/**
 * Extracts the Unix timestamp in milliseconds from a snowflake id.
 *
 * @category parts
 * @since 4.0.0
 */
export declare const timestamp: (snowflake: Snowflake) => number;
/**
 * Extracts the timestamp from a snowflake id as a `DateTime.Utc`.
 *
 * @category parts
 * @since 4.0.0
 */
export declare const dateTime: (snowflake: Snowflake) => DateTime.Utc;
/**
 * Extracts the machine id component from a snowflake id.
 *
 * @category parts
 * @since 4.0.0
 */
export declare const machineId: (snowflake: Snowflake) => MachineId;
/**
 * Extracts the per-machine sequence component from a snowflake id.
 *
 * @category parts
 * @since 4.0.0
 */
export declare const sequence: (snowflake: Snowflake) => number;
/**
 * Decomposes a snowflake id into its timestamp, machine id, and sequence parts.
 *
 * @category parts
 * @since 4.0.0
 */
export declare const toParts: (snowflake: Snowflake) => Snowflake.Parts;
/**
 * Creates a stateful snowflake generator using `Clock`.
 *
 * **Details**
 *
 * The generator starts with a random machine id, never moves generated timestamps
 * backward, resets the sequence each millisecond, and advances the timestamp when
 * more than 4096 ids are requested in the same millisecond.
 *
 * @category Generator
 * @since 4.0.0
 */
export declare const makeGenerator: Effect.Effect<Snowflake.Generator>;
declare const Generator_base: Context.ServiceClass<Generator, "effect/cluster/Snowflake/Generator", Snowflake.Generator>;
/**
 * Context service for a stateful snowflake id generator.
 *
 * @category Generator
 * @since 4.0.0
 */
export declare class Generator extends Generator_base {
}
/**
 * Layer that provides the default snowflake `Generator` service.
 *
 * @category Generator
 * @since 4.0.0
 */
export declare const layerGenerator: Layer.Layer<Generator>;
export {};
//# sourceMappingURL=Snowflake.d.ts.map