@barekey/sdk 0.2.0 → 0.3.0

package/src/client.ts

@@ -4,7 +4,7 @@ import {
   NetworkError,
   VariableNotFoundError,
 } from "./errors.js";
-import { BarekeyEnvHandle } from "./handle.js";
+import { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 import {
   evaluateDefinition,
   inferSelectedArmFromDecision,
@@ -14,6 +14,7 @@ import {
 import { getJson, postJson } from "./internal/http.js";
 import { validateRequirements } from "./internal/requirements.js";
 import { resolveRuntimeContext, type BarekeyRuntimeContext } from "./internal/runtime.js";
+import { createBarekeyClientSingletonKey } from "./internal/singleton.js";
 import { MemoryCache } from "./internal/cache.js";
 import { DEFAULT_TYPEGEN_TTL_MS, resolveTtlMilliseconds } from "./internal/ttl.js";
 import {
@@ -25,11 +26,11 @@ import {
 import type {
   BarekeyClientOptions,
   BarekeyEvaluatedValue,
-  BarekeyGeneratedTypeMap,
+  BarekeyGeneratedValueForKey,
+  BarekeyGeneratedValuesForKeys,
   BarekeyGetOptions,
   BarekeyJsonConfig,
   BarekeyKey,
-  BarekeyKnownKey,
   BarekeyTypegenResult,
   BarekeyVariableDefinition,
 } from "./types.js";
@@ -42,10 +43,15 @@ type EvaluateResponse = {
   name: string;
   kind: BarekeyEvaluatedValue["kind"];
   declaredType: BarekeyEvaluatedValue["declaredType"];
+  visibility: BarekeyEvaluatedValue["visibility"];
   value: string;
   decision?: BarekeyEvaluatedValue["decision"];
 };
 
+type EvaluateBatchResponse = {
+  values: Array<EvaluateResponse>;
+};
+
 type SharedTypegenWatcher = {
   intervalMs: number;
   inFlight: Promise<void> | null;
@@ -54,6 +60,7 @@ type SharedTypegenWatcher = {
 };
 
 const sharedTypegenWatchers = new Map<string, SharedTypegenWatcher>();
+const sharedClients = new Map<string, BarekeyClient>();
 
 function createDefaultFetch(): typeof globalThis.fetch {
   if (typeof globalThis.fetch === "function") {
@@ -81,9 +88,39 @@ function warnAutomaticTypegenFailure(error: unknown): void {
   console.warn(`[barekey] Automatic typegen refresh failed.\n${message}`);
 }
 
+function uniqueNames(names: readonly string[]): Array<string> {
+  return [...new Set(names)];
+}
+
+function mapValuesToRequestedOrder<TValue extends { name: string }>(
+  names: readonly string[],
+  values: readonly TValue[],
+): Array<TValue> {
+  const byName = new Map(values.map((value) => [value.name, value]));
+  return names.map((name) => {
+    const resolved = byName.get(name);
+    if (resolved === undefined) {
+      throw new VariableNotFoundError();
+    }
+    return resolved;
+  });
+}
+
+function resolveEvaluatedResponse(evaluated: EvaluateResponse): BarekeyEvaluatedValue {
+  return {
+    name: evaluated.name,
+    kind: evaluated.kind,
+    declaredType: evaluated.declaredType,
+    visibility: evaluated.visibility,
+    value: evaluated.value,
+    decision: evaluated.decision,
+    selectedArm: inferSelectedArmFromDecision(evaluated.decision),
+  };
+}
+
 export class BarekeyClient {
-  private readonly options: BarekeyClientOptions;
-  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly options!: BarekeyClientOptions;
+  private readonly fetchFn!: typeof globalThis.fetch;
   private readonly definitionCache = new MemoryCache<BarekeyVariableDefinition>();
   private readonly evaluationCache = new MemoryCache<BarekeyEvaluatedValue>();
   private runtimeContextPromise: Promise<BarekeyRuntimeContext> | null = null;
@@ -104,17 +141,37 @@ export class BarekeyClient {
     typegen?: BarekeyClientOptions["typegen"];
   });
   constructor(options: BarekeyClientOptions = {}) {
+    const singletonKey = createBarekeyClientSingletonKey(options);
+    const existing = sharedClients.get(singletonKey);
+    if (existing !== undefined) {
+      return existing;
+    }
+
     this.options = options;
     this.fetchFn = createDefaultFetch();
+    sharedClients.set(singletonKey, this);
   }
 
   get<TKey extends BarekeyKey>(
     name: TKey,
     options?: BarekeyGetOptions,
-  ): BarekeyEnvHandle<TKey extends BarekeyKnownKey ? BarekeyGeneratedTypeMap[TKey] : unknown>;
-  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown> {
+  ): BarekeyEnvHandle<BarekeyGeneratedValueForKey<TKey>>;
+  get<const TKeys extends readonly BarekeyKey[]>(
+    names: TKeys,
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvBatchHandle<BarekeyGeneratedValuesForKeys<TKeys>>;
+  get(
+    nameOrNames: string | readonly string[],
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvHandle<unknown> | BarekeyEnvBatchHandle<ReadonlyArray<unknown>> {
+    if (Array.isArray(nameOrNames)) {
+      return new BarekeyEnvBatchHandle(
+        async () => await this.resolveEvaluatedValues(nameOrNames, options),
+      );
+    }
+
     return new BarekeyEnvHandle(
-      async () => await this.resolveEvaluatedValue(name, options),
+      async () => await this.resolveEvaluatedValue(nameOrNames as string, options),
     );
   }
 
@@ -282,6 +339,10 @@ export class BarekeyClient {
   }
 
   private async fetchDefinitions(names?: Array<string>): Promise<Array<BarekeyVariableDefinition>> {
+    if (names !== undefined && names.length === 0) {
+      return [];
+    }
+
     const context = await this.getRuntimeContext();
     const response = await postJson<DefinitionsResponse>({
       fetchFn: this.fetchFn,
@@ -331,16 +392,42 @@ export class BarekeyClient {
     await this.requirementsPromise;
   }
 
-  private async getStaticDefinition(name: string): Promise<BarekeyVariableDefinition> {
+  private async getStaticDefinitions(
+    names: readonly string[],
+  ): Promise<Array<BarekeyVariableDefinition>> {
     await this.ensureRequirementsValidated();
     const context = await this.getRuntimeContext();
-    const cacheKey = this.buildDefinitionCacheKey(context, name);
-    const cached = this.definitionCache.get(cacheKey);
-    if (cached !== null) {
-      return cached;
+    const cachedDefinitions = new Map<string, BarekeyVariableDefinition>();
+    const missingNames: Array<string> = [];
+
+    for (const name of uniqueNames(names)) {
+      const cacheKey = this.buildDefinitionCacheKey(context, name);
+      const cached = this.definitionCache.get(cacheKey);
+      if (cached !== null) {
+        cachedDefinitions.set(name, cached);
+        continue;
+      }
+
+      missingNames.push(name);
     }
 
-    const definitions = await this.fetchDefinitions([name]);
+    if (missingNames.length > 0) {
+      for (const definition of await this.fetchDefinitions(missingNames)) {
+        cachedDefinitions.set(definition.name, definition);
+      }
+    }
+
+    return names.map((name) => {
+      const resolved = cachedDefinitions.get(name);
+      if (resolved === undefined) {
+        throw new VariableNotFoundError();
+      }
+      return resolved;
+    });
+  }
+
+  private async getStaticDefinition(name: string): Promise<BarekeyVariableDefinition> {
+    const definitions = await this.getStaticDefinitions([name]);
     const resolved = definitions[0];
     if (resolved === undefined) {
       throw new VariableNotFoundError();
@@ -356,61 +443,95 @@ export class BarekeyClient {
     return await evaluateDefinition(definition, options);
   }
 
-  private async resolveDynamicValue(
-    name: string,
+  private async resolveStaticValues(
+    names: readonly string[],
     options?: BarekeyGetOptions,
-  ): Promise<BarekeyEvaluatedValue> {
-    await this.ensureRequirementsValidated();
-    const context = await this.getRuntimeContext();
-    const cacheKey = this.buildEvaluationCacheKey(context, name, options);
-    const dynamic = options?.dynamic;
-    const dynamicTtlMs =
-      dynamic !== undefined && dynamic !== true
-        ? resolveTtlMilliseconds(dynamic.ttl, "dynamic.ttl")
-        : null;
-    if (dynamic !== true) {
-      const cached = this.evaluationCache.getRecord(cacheKey);
-      if (cached !== null && dynamicTtlMs !== null && Date.now() - cached.storedAtMs <= dynamicTtlMs) {
-        return cached.value;
-      }
-    }
+  ): Promise<Array<BarekeyEvaluatedValue>> {
+    const definitions = await this.getStaticDefinitions(names);
+    return await Promise.all(
+      definitions.map(async (definition) => await evaluateDefinition(definition, options)),
+    );
+  }
 
-    let resolved: BarekeyEvaluatedValue;
+  private async fetchDynamicValues(
+    names: readonly string[],
+    context: BarekeyRuntimeContext,
+    options?: BarekeyGetOptions,
+  ): Promise<Array<BarekeyEvaluatedValue>> {
     try {
-      const evaluated = await postJson<EvaluateResponse>({
+      if (names.length === 1) {
+        const evaluated = await postJson<EvaluateResponse>({
+          fetchFn: this.fetchFn,
+          baseUrl: context.baseUrl,
+          path: "/v1/env/evaluate",
+          payload: {
+            orgSlug: context.organization,
+            projectSlug: context.project,
+            stageSlug: context.environment,
+            name: names[0],
+            seed: options?.seed,
+            key: options?.key,
+          },
+          auth: context.auth,
+        });
+
+        return [resolveEvaluatedResponse(evaluated)];
+      }
+
+      const evaluated = await postJson<EvaluateBatchResponse>({
         fetchFn: this.fetchFn,
         baseUrl: context.baseUrl,
-        path: "/v1/env/evaluate",
+        path: "/v1/env/evaluate-batch",
         payload: {
           orgSlug: context.organization,
           projectSlug: context.project,
           stageSlug: context.environment,
-          name,
+          names,
           seed: options?.seed,
           key: options?.key,
         },
         auth: context.auth,
       });
 
-      resolved = {
-        name: evaluated.name,
-        kind: evaluated.kind,
-        declaredType: evaluated.declaredType,
-        value: evaluated.value,
-        decision: evaluated.decision,
-        selectedArm: inferSelectedArmFromDecision(evaluated.decision),
-      };
+      return mapValuesToRequestedOrder(
+        names,
+        evaluated.values.map((value) => resolveEvaluatedResponse(value)),
+      );
     } catch (error: unknown) {
       if (!(error instanceof BillingUnavailableError)) {
         throw error;
       }
 
-      const freshDefinitions = await this.fetchDefinitions([name]);
-      const freshDefinition = freshDefinitions[0];
-      if (freshDefinition === undefined) {
-        throw new VariableNotFoundError();
+      const definitions = await this.getStaticDefinitions(names);
+      return await Promise.all(
+        definitions.map(async (definition) => await evaluateDefinition(definition, options)),
+      );
+    }
+  }
+
+  private async resolveDynamicValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const cacheKey = this.buildEvaluationCacheKey(context, name, options);
+    const dynamic = options?.dynamic;
+    const dynamicTtlMs =
+      dynamic !== undefined && dynamic !== true
+        ? resolveTtlMilliseconds(dynamic.ttl, "dynamic.ttl")
+        : null;
+    if (dynamic !== true) {
+      const cached = this.evaluationCache.getRecord(cacheKey);
+      if (cached !== null && dynamicTtlMs !== null && Date.now() - cached.storedAtMs <= dynamicTtlMs) {
+        return cached.value;
       }
-      resolved = await evaluateDefinition(freshDefinition, options);
+    }
+
+    const resolvedValues = await this.fetchDynamicValues([name], context, options);
+    const resolved = resolvedValues[0];
+    if (resolved === undefined) {
+      throw new VariableNotFoundError();
     }
 
     if (dynamicTtlMs !== null) {
@@ -422,6 +543,45 @@ export class BarekeyClient {
     return resolved;
   }
 
+  private async resolveDynamicValues(
+    names: readonly string[],
+    options?: BarekeyGetOptions,
+  ): Promise<Array<BarekeyEvaluatedValue>> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const dynamic = options?.dynamic;
+    const dynamicTtlMs =
+      dynamic !== undefined && dynamic !== true
+        ? resolveTtlMilliseconds(dynamic.ttl, "dynamic.ttl")
+        : null;
+    const resolvedValues = new Map<string, BarekeyEvaluatedValue>();
+    const missingNames: Array<string> = [];
+
+    for (const name of uniqueNames(names)) {
+      const cacheKey = this.buildEvaluationCacheKey(context, name, options);
+      if (dynamic !== true) {
+        const cached = this.evaluationCache.getRecord(cacheKey);
+        if (cached !== null && dynamicTtlMs !== null && Date.now() - cached.storedAtMs <= dynamicTtlMs) {
+          resolvedValues.set(name, cached.value);
+          continue;
+        }
+      }
+
+      missingNames.push(name);
+    }
+
+    if (missingNames.length > 0) {
+      for (const resolved of await this.fetchDynamicValues(missingNames, context, options)) {
+        resolvedValues.set(resolved.name, resolved);
+        if (dynamicTtlMs !== null) {
+          this.evaluationCache.set(this.buildEvaluationCacheKey(context, resolved.name, options), resolved);
+        }
+      }
+    }
+
+    return mapValuesToRequestedOrder(names, [...resolvedValues.values()]);
+  }
+
   private async resolveEvaluatedValue(
     name: string,
     options?: BarekeyGetOptions,
@@ -434,4 +594,27 @@ export class BarekeyClient {
     }
     return await this.resolveDynamicValue(name, options);
   }
+
+  private async resolveEvaluatedValues(
+    names: readonly string[],
+    options?: BarekeyGetOptions,
+  ): Promise<Array<BarekeyEvaluatedValue>> {
+    if (names.length === 0) {
+      return [];
+    }
+
+    if (uniqueNames(names).length === 1) {
+      const resolved = await this.resolveEvaluatedValue(names[0] ?? "", options);
+      return names.map(() => resolved);
+    }
+
+    const context = await this.getRuntimeContext();
+    this.ensureTypegenWatcher(context);
+    validateDynamicOptions(options);
+    if (options?.dynamic === undefined) {
+      return await this.resolveStaticValues(names, options);
+    }
+
+    return await this.resolveDynamicValues(names, options);
+  }
 }

package/src/handle.ts

@@ -2,7 +2,12 @@ import {
   coerceEvaluatedValue,
   parseDeclaredValue,
 } from "./internal/evaluate.js";
-import type { BarekeyCoerceTarget, BarekeyEvaluatedValue } from "./types.js";
+import type {
+  BarekeyCoerceTarget,
+  BarekeyEvaluatedValue,
+  BarekeyResolvedRecord,
+  BarekeyResolvedRecords,
+} from "./types.js";
 
 type BarekeyCoercibleEnvMarker = {
   readonly __barekey?: {
@@ -10,10 +15,22 @@ type BarekeyCoercibleEnvMarker = {
   };
 };
 
+function buildResolvedRecord<TValue>(
+  resolved: BarekeyEvaluatedValue,
+  value: TValue,
+): BarekeyResolvedRecord<TValue> {
+  return {
+    ...resolved,
+    rawValue: resolved.value,
+    value,
+  };
+}
+
 export class BarekeyEnvHandle<TValue = unknown> implements PromiseLike<TValue> {
   private readonly resolveEvaluatedValue: () => Promise<BarekeyEvaluatedValue>;
   private readonly transform: (resolved: BarekeyEvaluatedValue) => Promise<TValue>;
   private evaluatedValuePromise: Promise<BarekeyEvaluatedValue> | null = null;
+  private resolvedRecordPromise: Promise<BarekeyResolvedRecord<TValue>> | null = null;
 
   constructor(
     resolveEvaluatedValue: () => Promise<BarekeyEvaluatedValue>,
@@ -26,7 +43,7 @@ export class BarekeyEnvHandle<TValue = unknown> implements PromiseLike<TValue> {
   }
 
   private async resolveValue(): Promise<TValue> {
-    return await this.transform(await this.getEvaluatedValue());
+    return (await this.inspect()).value;
   }
 
   private async getEvaluatedValue(): Promise<BarekeyEvaluatedValue> {
@@ -36,6 +53,18 @@ export class BarekeyEnvHandle<TValue = unknown> implements PromiseLike<TValue> {
     return await this.evaluatedValuePromise;
   }
 
+  async inspect(): Promise<BarekeyResolvedRecord<TValue>> {
+    if (this.resolvedRecordPromise === null) {
+      this.resolvedRecordPromise = (async () => {
+        const resolved = await this.getEvaluatedValue();
+        const value = await this.transform(resolved);
+        return buildResolvedRecord(resolved, value);
+      })();
+    }
+
+    return await this.resolvedRecordPromise;
+  }
+
   coerce<TCoerced = unknown>(
     this: [TValue] extends [BarekeyCoercibleEnvMarker] ? BarekeyEnvHandle<TValue> : never,
     target: BarekeyCoerceTarget,
@@ -65,3 +94,62 @@ export class BarekeyEnvHandle<TValue = unknown> implements PromiseLike<TValue> {
     return this.resolveValue().finally(onfinally ?? undefined);
   }
 }
+
+export class BarekeyEnvBatchHandle<
+  TValues extends ReadonlyArray<unknown> = Array<unknown>,
+> implements PromiseLike<TValues>
+{
+  private readonly resolveEvaluatedValues: () => Promise<ReadonlyArray<BarekeyEvaluatedValue>>;
+  private evaluatedValuesPromise: Promise<ReadonlyArray<BarekeyEvaluatedValue>> | null = null;
+  private resolvedRecordsPromise: Promise<BarekeyResolvedRecords<TValues>> | null = null;
+
+  constructor(resolveEvaluatedValues: () => Promise<ReadonlyArray<BarekeyEvaluatedValue>>) {
+    this.resolveEvaluatedValues = resolveEvaluatedValues;
+  }
+
+  private async getEvaluatedValues(): Promise<ReadonlyArray<BarekeyEvaluatedValue>> {
+    if (this.evaluatedValuesPromise === null) {
+      this.evaluatedValuesPromise = this.resolveEvaluatedValues();
+    }
+    return await this.evaluatedValuesPromise;
+  }
+
+  async inspect(): Promise<BarekeyResolvedRecords<TValues>> {
+    if (this.resolvedRecordsPromise === null) {
+      this.resolvedRecordsPromise = (async () => {
+        const resolvedValues = await this.getEvaluatedValues();
+        const records = await Promise.all(
+          resolvedValues.map(async (resolved) => {
+            const value = parseDeclaredValue(resolved.value, resolved.declaredType);
+            return buildResolvedRecord(resolved, value);
+          }),
+        );
+        return records as BarekeyResolvedRecords<TValues>;
+      })();
+    }
+
+    return await this.resolvedRecordsPromise;
+  }
+
+  private async resolveValues(): Promise<TValues> {
+    const resolvedRecords = await this.inspect();
+    return resolvedRecords.map((resolved) => resolved.value) as unknown as TValues;
+  }
+
+  then<TResult1 = TValues, TResult2 = never>(
+    onfulfilled?: ((value: TValues) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.resolveValues().then(onfulfilled ?? undefined, onrejected ?? undefined);
+  }
+
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<TValues | TResult> {
+    return this.resolveValues().catch(onrejected ?? undefined);
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<TValues> {
+    return this.resolveValues().finally(onfinally ?? undefined);
+  }
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 export { BarekeyClient } from "./client.js";
 export { PublicBarekeyClient } from "./public-client.js";
-export { BarekeyEnvHandle } from "./handle.js";
+export { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 export {
   BarekeyError,
   BillingUnavailableError,
@@ -44,12 +44,17 @@ export type {
   BarekeyCoerceTarget,
   BarekeyDeclaredType,
   BarekeyErrorCode,
+  BarekeyEvaluatedValue,
   BarekeyGeneratedTypeMap,
+  BarekeyGeneratedValueForKey,
+  BarekeyGeneratedValuesForKeys,
   BarekeyGetOptions,
   BarekeyJsonConfig,
   BarekeyKey,
   BarekeyLiteralString,
   BarekeyKnownKey,
+  BarekeyResolvedRecord,
+  BarekeyResolvedRecords,
   BarekeyResolvedKind,
   BarekeyRolloutMilestone,
   BarekeyStandardSchemaV1,
@@ -57,14 +62,19 @@ export type {
   BarekeyTemporalInstantLike,
   BarekeyTtlInput,
   BarekeyTypegenResult,
+  BarekeyValueForGeneratedMap,
+  BarekeyValuesForGeneratedMap,
   Env,
   Linear,
   Secret,
+  BarekeyVisibility,
 } from "./types.js";
 
 export type {
   BarekeyPublicGeneratedTypeMap,
   BarekeyPublicKey,
   BarekeyPublicKnownKey,
+  BarekeyPublicValueForKey,
+  BarekeyPublicValuesForKeys,
   PublicBarekeyClientOptions,
 } from "./public-types.js";

package/src/internal/evaluate.ts

@@ -196,6 +196,7 @@ export async function evaluateDefinition(
       name: definition.name,
       kind: definition.kind,
       declaredType: definition.declaredType,
+      visibility: definition.visibility,
       value: definition.value,
     };
   }
@@ -213,6 +214,7 @@ export async function evaluateDefinition(
       name: definition.name,
       kind: definition.kind,
       declaredType: definition.declaredType,
+      visibility: definition.visibility,
       value: selectedArm === "A" ? definition.valueA : definition.valueB,
       selectedArm,
       decision: {
@@ -235,6 +237,7 @@ export async function evaluateDefinition(
     name: definition.name,
     kind: definition.kind,
     declaredType: definition.declaredType,
+    visibility: definition.visibility,
     value: selectedArm === "A" ? definition.valueA : definition.valueB,
     selectedArm,
     decision: {