add preregisteredWords options to frequency metric key type (#2377)

.changeset/breezy-countries-warn.md

@@ -0,0 +1,16 @@
+---
+"effect": minor
+---
+
+add preregisteredWords option to frequency metric key type
+
+You can use this to register a list of words to pre-populate the value of the
+metric.
+
+```ts
+import { Metric } from "effect";
+
+const counts = Metric.frequency("counts", {
+  preregisteredWords: ["a", "b", "c"],
+}).register();
+```

packages/effect/src/Metric.ts

@@ -208,12 +208,19 @@ export const counter: {
  * @example
  * import * as Metric from "effect/Metric"
  *
- * const errorFrequency = Metric.frequency("error_frequency", "Counts the occurrences of errors.");
+ * const errorFrequency = Metric.frequency("error_frequency", {
+ *    description: "Counts the occurrences of errors."
+ * });
  *
  * @since 2.0.0
  * @category constructors
  */
-export const frequency: (name: string, description?: string) => Metric.Frequency<string> = internal.frequency
+export const frequency: (
+  name: string,
+  options?:
+    | { readonly description?: string | undefined; readonly preregisteredWords?: ReadonlyArray<string> | undefined }
+    | undefined
+) => Metric.Frequency<string> = internal.frequency
 
 /**
  * Returns a new metric that is powered by this one, but which accepts updates

packages/effect/src/MetricKey.ts

@@ -132,7 +132,15 @@ export const counter: {
  * @since 2.0.0
  * @category constructors
  */
-export const frequency: (name: string, description?: string) => MetricKey.Frequency = internal.frequency
+export const frequency: (
+  name: string,
+  options?:
+    | {
+      readonly description?: string | undefined
+      readonly preregisteredWords?: ReadonlyArray<string> | undefined
+    }
+    | undefined
+) => MetricKey.Frequency = internal.frequency
 
 /**
  * Creates a metric key for a gauge, with the specified name.

packages/effect/src/MetricKeyType.ts

@@ -113,6 +113,7 @@ export declare namespace MetricKeyType {
    */
   export type Frequency = MetricKeyType<string, MetricState.MetricState.Frequency> & {
     readonly [FrequencyKeyTypeTypeId]: FrequencyKeyTypeTypeId
+    readonly preregisteredWords: ReadonlyArray<string>
   }
 
   /**
@@ -193,7 +194,11 @@ export const counter: <A extends number | bigint>() => MetricKeyType.Counter<A>
  * @since 2.0.0
  * @category constructors
  */
-export const frequency: MetricKeyType.Frequency = internal.frequency
+export const frequency: (
+  options?: {
+    readonly preregisteredWords?: ReadonlyArray<string> | undefined
+  } | undefined
+) => MetricKeyType.Frequency = internal.frequency
 
 /**
  * @since 2.0.0

packages/effect/src/internal/metric.ts

@@ -98,8 +98,10 @@ export const counter: {
 } = (name, options) => fromMetricKey(metricKey.counter(name, options as any)) as any
 
 /** @internal */
-export const frequency = (name: string, description?: string): Metric.Metric.Frequency<string> =>
-  fromMetricKey(metricKey.frequency(name, description))
+export const frequency = (name: string, options?: {
+  readonly description?: string | undefined
+  readonly preregisteredWords?: ReadonlyArray<string> | undefined
+}): Metric.Metric.Frequency<string> => fromMetricKey(metricKey.frequency(name, options))
 
 /** @internal */
 export const withConstantInput = dual<

packages/effect/src/internal/metric/hook.ts

@@ -78,8 +78,11 @@ export const counter = <A extends (number | bigint)>(
 }
 
 /** @internal */
-export const frequency = (_key: MetricKey.MetricKey.Frequency): MetricHook.MetricHook.Frequency => {
+export const frequency = (key: MetricKey.MetricKey.Frequency): MetricHook.MetricHook.Frequency => {
   const values = new Map<string, number>()
+  for (const word of key.keyType.preregisteredWords) {
+    values.set(word, 0)
+  }
   const update = (word: string) => {
     const slotCount = values.get(word) ?? 0
     values.set(word, slotCount + 1)

packages/effect/src/internal/metric/key.ts

@@ -83,8 +83,11 @@ export const counter: {
   )
 
 /** @internal */
-export const frequency = (name: string, description?: string): MetricKey.MetricKey.Frequency =>
-  new MetricKeyImpl(name, metricKeyType.frequency, Option.fromNullable(description))
+export const frequency = (name: string, options?: {
+  readonly description?: string | undefined
+  readonly preregisteredWords?: ReadonlyArray<string> | undefined
+}): MetricKey.MetricKey.Frequency =>
+  new MetricKeyImpl(name, metricKeyType.frequency(options), Option.fromNullable(options?.description))
 
 /** @internal */
 export const gauge: {

packages/effect/src/internal/metric/keyType.ts

@@ -86,7 +86,8 @@ const FrequencyKeyTypeHash = Hash.string(FrequencyKeyTypeSymbolKey)
 /** @internal */
 class FrequencyKeyType implements MetricKeyType.MetricKeyType.Frequency {
   readonly [MetricKeyTypeTypeId] = metricKeyTypeVariance
-  readonly [FrequencyKeyTypeTypeId]: MetricKeyType.FrequencyKeyTypeTypeId = FrequencyKeyTypeTypeId;
+  readonly [FrequencyKeyTypeTypeId]: MetricKeyType.FrequencyKeyTypeTypeId = FrequencyKeyTypeTypeId
+  constructor(readonly preregisteredWords: ReadonlyArray<string>) {}
   [Hash.symbol](): number {
     return FrequencyKeyTypeHash
   }
@@ -192,7 +193,9 @@ export const counter: <A extends number | bigint>(options?: {
  * @since 2.0.0
  * @category constructors
  */
-export const frequency: MetricKeyType.MetricKeyType.Frequency = new FrequencyKeyType()
+export const frequency = (options?: {
+  readonly preregisteredWords?: ReadonlyArray<string> | undefined
+}): MetricKeyType.MetricKeyType.Frequency => new FrequencyKeyType(options?.preregisteredWords ?? [])
 
 /**
  * @since 2.0.0