@barekey/sdk 0.2.0 → 0.3.0

package/src/internal/singleton.ts

@@ -0,0 +1,183 @@
+import type { PublicBarekeyClientOptions } from "../public-types.js";
+import type {
+  BarekeyClientOptions,
+  BarekeyJsonConfig,
+  BarekeyStandardSchemaV1,
+  BarekeyTtlInput,
+} from "../types.js";
+import { normalizeBaseUrl } from "./http.js";
+
+const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";
+
+const referenceIds = new WeakMap<object, number>();
+let nextReferenceId = 1;
+
+function readConfigString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  return value.trim();
+}
+
+function getReferenceId(value: object): number {
+  const existing = referenceIds.get(value);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const nextId = nextReferenceId;
+  nextReferenceId += 1;
+  referenceIds.set(value, nextId);
+  return nextId;
+}
+
+function safeCurrentWorkingDirectory(): string {
+  if (typeof process === "undefined" || typeof process.cwd !== "function") {
+    return "";
+  }
+
+  return process.cwd();
+}
+
+function normalizeJsonScope(
+  value: BarekeyJsonConfig | undefined,
+): { organization: string | null; project: string | null; environment: string | null } | null {
+  if (value === undefined) {
+    return null;
+  }
+
+  return {
+    organization: readConfigString(value.organization ?? value.org),
+    project: readConfigString(value.project),
+    environment: readConfigString(value.environment ?? value.stage),
+  };
+}
+
+function normalizeScopeKey(
+  options:
+    | BarekeyClientOptions
+    | PublicBarekeyClientOptions,
+): { organization: string | null; project: string | null; environment: string | null } | {
+  cwd: string;
+} {
+  const jsonScope = normalizeJsonScope("json" in options ? options.json : undefined);
+  if (jsonScope !== null) {
+    return jsonScope;
+  }
+
+  const organization = "organization" in options ? readConfigString(options.organization) : null;
+  const project = "project" in options ? readConfigString(options.project) : null;
+  const environment = "environment" in options ? readConfigString(options.environment) : null;
+  if (organization !== null || project !== null || environment !== null) {
+    return {
+      organization,
+      project,
+      environment,
+    };
+  }
+
+  return {
+    cwd: safeCurrentWorkingDirectory(),
+  };
+}
+
+function normalizeTtlKey(value: BarekeyTtlInput | undefined): unknown {
+  if (value === undefined) {
+    return null;
+  }
+
+  if (typeof value === "number") {
+    return {
+      kind: "milliseconds",
+      value,
+    };
+  }
+
+  if (value instanceof Date) {
+    return {
+      kind: "date",
+      value: value.getTime(),
+    };
+  }
+
+  if (typeof value === "object" && value !== null && "epochMilliseconds" in value) {
+    const epochMilliseconds = (value as { epochMilliseconds?: unknown }).epochMilliseconds;
+    if (typeof epochMilliseconds === "number") {
+      return {
+        kind: "temporal",
+        value: epochMilliseconds,
+      };
+    }
+  }
+
+  return {
+    kind: "reference",
+    value: getReferenceId(value as object),
+  };
+}
+
+function normalizeRequirementsKey(value: BarekeyStandardSchemaV1 | undefined): unknown {
+  if (value === undefined) {
+    return null;
+  }
+
+  return {
+    kind: "reference",
+    value: getReferenceId(value as object),
+  };
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+
+  if (typeof value === "undefined") {
+    return '"__undefined__"';
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([left], [right]) =>
+      left.localeCompare(right),
+    );
+    return `{${entries
+      .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`)
+      .join(",")}}`;
+  }
+
+  return JSON.stringify(String(value));
+}
+
+export function createBarekeyClientSingletonKey(options: BarekeyClientOptions): string {
+  return stableStringify({
+    kind: "server",
+    scope: normalizeScopeKey(options),
+    requirements: normalizeRequirementsKey(options.requirements),
+    typegen:
+      options.typegen === false
+        ? false
+        : {
+            ttl: normalizeTtlKey(options.typegen?.ttl),
+          },
+  });
+}
+
+export function createPublicBarekeyClientSingletonKey(
+  options: PublicBarekeyClientOptions,
+): string {
+  return stableStringify({
+    kind: "public",
+    scope: normalizeScopeKey(options),
+    requirements: normalizeRequirementsKey(options.requirements),
+    baseUrl: normalizeBaseUrl(options.baseUrl?.trim() || DEFAULT_BAREKEY_API_URL),
+  });
+}

package/src/key-types.typecheck.ts

@@ -1,5 +1,5 @@
 import type { BarekeyClient } from "./client.js";
-import type { BarekeyEnvHandle } from "./handle.js";
+import type { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 import type { PublicBarekeyClient } from "./public-client.js";
 import type { Env, Secret } from "./types.js";
 import type {
@@ -34,15 +34,21 @@ type IsEqual<TLeft, TRight> = (<TValue>() => TValue extends TLeft ? 1 : 2) exten
   ? true
   : false;
 
-type UnwrapHandle<TValue> = TValue extends BarekeyEnvHandle<infer TResolved> ? TResolved : never;
+type UnwrapHandle<TValue> = TValue extends BarekeyEnvHandle<infer TResolved>
+  ? TResolved
+  : TValue extends BarekeyEnvBatchHandle<infer TResolved>
+    ? TResolved
+    : never;
 
 declare const client: BarekeyClient;
 declare const publicClient: PublicBarekeyClient;
 
 const privateKnownHandle = client.get("PRIVATE_TOKEN");
 const privateUnknownHandle = client.get("SOME_RUNTIME_KEY");
+const privateTupleHandle = client.get(["PRIVATE_TOKEN", "SOME_RUNTIME_KEY"] as const);
 const publicKnownHandle = publicClient.get("PUBLIC_THEME");
 const publicUnknownHandle = publicClient.get("SOME_RUNTIME_KEY");
+const publicTupleHandle = publicClient.get(["PUBLIC_THEME", "SOME_RUNTIME_KEY"] as const);
 
 type _barekeyKnownKeyStillExact = Assert<IsEqual<BarekeyKnownKey, "PRIVATE_TOKEN">>;
 type _barekeyPublicKnownKeyStillExact = Assert<IsEqual<BarekeyPublicKnownKey, "PUBLIC_THEME">>;
@@ -64,5 +70,11 @@ type _publicKnownHandleKeepsGeneratedValue = Assert<
 type _publicUnknownHandleFallsBackToUnknown = Assert<
   IsEqual<UnwrapHandle<typeof publicUnknownHandle>, unknown>
 >;
+type _privateTupleHandleMapsKnownAndUnknownKeys = Assert<
+  IsEqual<UnwrapHandle<typeof privateTupleHandle>, readonly [BarekeyGeneratedTypeMap["PRIVATE_TOKEN"], unknown]>
+>;
+type _publicTupleHandleMapsKnownAndUnknownKeys = Assert<
+  IsEqual<UnwrapHandle<typeof publicTupleHandle>, readonly [BarekeyPublicGeneratedTypeMap["PUBLIC_THEME"], unknown]>
+>;
 
 export {};

package/src/public-client.ts

@@ -1,5 +1,5 @@
 import { VariableNotFoundError } from "./errors.js";
-import { BarekeyEnvHandle } from "./handle.js";
+import { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 import {
   evaluateDefinition,
   parseDeclaredValue,
@@ -12,11 +12,12 @@ import {
   resolvePublicRuntimeContext,
   type BarekeyPublicRuntimeContext,
 } from "./internal/public-runtime.js";
+import { createPublicBarekeyClientSingletonKey } from "./internal/singleton.js";
 import { resolveTtlMilliseconds } from "./internal/ttl.js";
 import type {
-  BarekeyPublicGeneratedTypeMap,
+  BarekeyPublicValueForKey,
+  BarekeyPublicValuesForKeys,
   BarekeyPublicKey,
-  BarekeyPublicKnownKey,
   PublicBarekeyClientOptions,
 } from "./public-types.js";
 import type {
@@ -30,6 +31,8 @@ type DefinitionsResponse = {
   definitions: Array<BarekeyVariableDefinition>;
 };
 
+const sharedClients = new Map<string, PublicBarekeyClient>();
+
 function createDefaultFetch(): typeof globalThis.fetch {
   if (typeof globalThis.fetch === "function") {
     return globalThis.fetch.bind(globalThis);
@@ -40,9 +43,27 @@ function createDefaultFetch(): typeof globalThis.fetch {
   }) as typeof globalThis.fetch;
 }
 
+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;
+  });
+}
+
 export class PublicBarekeyClient {
-  private readonly options: PublicBarekeyClientOptions;
-  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly options!: PublicBarekeyClientOptions;
+  private readonly fetchFn!: typeof globalThis.fetch;
   private readonly definitionCache = new MemoryCache<BarekeyVariableDefinition>();
   private readonly evaluationCache = new MemoryCache<BarekeyEvaluatedValue>();
   private runtimeContextPromise: Promise<BarekeyPublicRuntimeContext> | null = null;
@@ -62,19 +83,37 @@ export class PublicBarekeyClient {
     baseUrl?: string;
   });
   constructor(options: PublicBarekeyClientOptions = {}) {
+    const singletonKey = createPublicBarekeyClientSingletonKey(options);
+    const existing = sharedClients.get(singletonKey);
+    if (existing !== undefined) {
+      return existing;
+    }
+
     this.options = options;
     this.fetchFn = createDefaultFetch();
+    sharedClients.set(singletonKey, this);
   }
 
   get<TKey extends BarekeyPublicKey>(
     name: TKey,
     options?: BarekeyGetOptions,
-  ): BarekeyEnvHandle<
-    TKey extends BarekeyPublicKnownKey ? BarekeyPublicGeneratedTypeMap[TKey] : unknown
-  >;
-  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown> {
+  ): BarekeyEnvHandle<BarekeyPublicValueForKey<TKey>>;
+  get<const TKeys extends readonly BarekeyPublicKey[]>(
+    names: TKeys,
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvBatchHandle<BarekeyPublicValuesForKeys<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),
     );
   }
 
@@ -111,6 +150,10 @@ export class PublicBarekeyClient {
   }
 
   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,
@@ -159,16 +202,42 @@ export class PublicBarekeyClient {
     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);
+    }
+
+    if (missingNames.length > 0) {
+      for (const definition of await this.fetchDefinitions(missingNames)) {
+        cachedDefinitions.set(definition.name, definition);
+      }
     }
 
-    const definitions = await this.fetchDefinitions([name]);
+    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();
@@ -184,6 +253,16 @@ export class PublicBarekeyClient {
     return await evaluateDefinition(definition, options);
   }
 
+  private async resolveStaticValues(
+    names: readonly string[],
+    options?: BarekeyGetOptions,
+  ): Promise<Array<BarekeyEvaluatedValue>> {
+    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,
@@ -218,6 +297,49 @@ export class PublicBarekeyClient {
     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) {
+      const freshDefinitions = await this.getStaticDefinitions(missingNames);
+      const freshValues = await Promise.all(
+        freshDefinitions.map(async (definition) => await evaluateDefinition(definition, options)),
+      );
+      for (const resolved of freshValues) {
+        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,
@@ -228,4 +350,25 @@ export class PublicBarekeyClient {
     }
     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);
+    }
+
+    validateDynamicOptions(options);
+    if (options?.dynamic === undefined) {
+      return await this.resolveStaticValues(names, options);
+    }
+
+    return await this.resolveDynamicValues(names, options);
+  }
 }

package/src/public-types.ts

@@ -29,6 +29,8 @@ import type {
   BarekeyJsonConfig,
   BarekeyLiteralString,
   BarekeyStandardSchemaV1,
+  BarekeyValueForGeneratedMap,
+  BarekeyValuesForGeneratedMap,
 } from "./types.js";
 
 export interface BarekeyPublicGeneratedTypeMap {}
@@ -37,6 +39,14 @@ export type BarekeyPublicKnownKey = Extract<keyof BarekeyPublicGeneratedTypeMap,
 
 export type BarekeyPublicKey = BarekeyPublicKnownKey | BarekeyLiteralString;
 
+export type BarekeyPublicValueForKey<TKey extends string> = BarekeyValueForGeneratedMap<
+  BarekeyPublicGeneratedTypeMap,
+  TKey
+>;
+
+export type BarekeyPublicValuesForKeys<TKeys extends readonly string[]> =
+  BarekeyValuesForGeneratedMap<BarekeyPublicGeneratedTypeMap, TKeys>;
+
 type BarekeyPublicBaseClientOptions = {
   requirements?: BarekeyStandardSchemaV1;
   baseUrl?: string;

package/src/public.ts

@@ -1,5 +1,5 @@
 export { PublicBarekeyClient } from "./public-client.js";
-export { BarekeyEnvHandle } from "./handle.js";
+export { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 export {
   BarekeyError,
   BillingUnavailableError,
@@ -47,6 +47,8 @@ export type {
   BarekeyGetOptions,
   BarekeyJsonConfig,
   BarekeyLiteralString,
+  BarekeyResolvedRecord,
+  BarekeyResolvedRecords,
   BarekeyResolvedKind,
   BarekeyRolloutFunction,
   BarekeyRolloutMatchedRule,
@@ -55,7 +57,10 @@ export type {
   BarekeyTemporalInstant,
   BarekeyTemporalInstantLike,
   BarekeyTtlInput,
+  BarekeyValueForGeneratedMap,
+  BarekeyValuesForGeneratedMap,
   BarekeyVariableDefinition,
+  BarekeyVisibility,
   EaseInOut,
   Env,
   Linear,
@@ -67,5 +72,7 @@ export type {
   BarekeyPublicGeneratedTypeMap,
   BarekeyPublicKey,
   BarekeyPublicKnownKey,
+  BarekeyPublicValueForKey,
+  BarekeyPublicValuesForKeys,
   PublicBarekeyClientOptions,
 } from "./public-types.js";

package/src/server.ts

@@ -1,5 +1,5 @@
 export { BarekeyClient } from "./client.js";
-export { BarekeyEnvHandle } from "./handle.js";
+export { BarekeyEnvBatchHandle, BarekeyEnvHandle } from "./handle.js";
 export {
   BarekeyError,
   BillingUnavailableError,
@@ -44,11 +44,15 @@ export type {
   BarekeyDeclaredType,
   BarekeyErrorCode,
   BarekeyGeneratedTypeMap,
+  BarekeyGeneratedValueForKey,
+  BarekeyGeneratedValuesForKeys,
   BarekeyGetOptions,
   BarekeyJsonConfig,
   BarekeyKey,
   BarekeyLiteralString,
   BarekeyKnownKey,
+  BarekeyResolvedRecord,
+  BarekeyResolvedRecords,
   BarekeyResolvedKind,
   BarekeyRolloutMilestone,
   BarekeyStandardSchemaV1,
@@ -56,6 +60,9 @@ export type {
   BarekeyTemporalInstantLike,
   BarekeyTtlInput,
   BarekeyTypegenResult,
+  BarekeyValueForGeneratedMap,
+  BarekeyValuesForGeneratedMap,
+  BarekeyVisibility,
   Env,
   Linear,
   Secret,

package/src/types.ts

@@ -1,4 +1,5 @@
 export type BarekeyResolvedKind = "secret" | "ab_roll" | "rollout";
+export type BarekeyVisibility = "private" | "public";
 
 export type BarekeyDeclaredType = "string" | "boolean" | "int64" | "float" | "date" | "json";
 
@@ -63,6 +64,28 @@ export type BarekeyLiteralString = string & {};
 
 export type BarekeyKey = BarekeyKnownKey | BarekeyLiteralString;
 
+export type BarekeyValueForGeneratedMap<
+  TMap extends object,
+  TKey extends string,
+> = TKey extends Extract<keyof TMap, string> ? TMap[TKey] : unknown;
+
+export type BarekeyValuesForGeneratedMap<
+  TMap extends object,
+  TKeys extends readonly string[],
+> = {
+  [TIndex in keyof TKeys]: TKeys[TIndex] extends string
+    ? BarekeyValueForGeneratedMap<TMap, TKeys[TIndex]>
+    : never;
+};
+
+export type BarekeyGeneratedValueForKey<TKey extends string> = BarekeyValueForGeneratedMap<
+  BarekeyGeneratedTypeMap,
+  TKey
+>;
+
+export type BarekeyGeneratedValuesForKeys<TKeys extends readonly string[]> =
+  BarekeyValuesForGeneratedMap<BarekeyGeneratedTypeMap, TKeys>;
+
 export type BarekeyRolloutMilestone = {
   at: string;
   percentage: number;
@@ -87,22 +110,34 @@ export type BarekeyEvaluatedValue = {
   name: string;
   kind: BarekeyResolvedKind;
   declaredType: BarekeyDeclaredType;
+  visibility: BarekeyVisibility;
   value: string;
   decision?: BarekeyDecision;
   selectedArm?: "A" | "B";
 };
 
+export type BarekeyResolvedRecord<TValue = unknown> = Omit<BarekeyEvaluatedValue, "value"> & {
+  value: TValue;
+  rawValue: string;
+};
+
+export type BarekeyResolvedRecords<TValues extends ReadonlyArray<unknown>> = {
+  [TIndex in keyof TValues]: BarekeyResolvedRecord<TValues[TIndex]>;
+};
+
 export type BarekeyVariableDefinition =
   | {
       name: string;
       kind: "secret";
       declaredType: BarekeyDeclaredType;
+      visibility: BarekeyVisibility;
       value: string;
     }
   | {
       name: string;
       kind: "ab_roll";
       declaredType: BarekeyDeclaredType;
+      visibility: BarekeyVisibility;
       valueA: string;
       valueB: string;
       chance: number;
@@ -111,6 +146,7 @@ export type BarekeyVariableDefinition =
       name: string;
       kind: "rollout";
       declaredType: BarekeyDeclaredType;
+      visibility: BarekeyVisibility;
       valueA: string;
       valueB: string;
       rolloutFunction: BarekeyRolloutFunction;