@valon-technologies/gestalt 0.0.1-alpha.1

package/src/schema.ts

@@ -0,0 +1,219 @@
+export type CatalogType = "string" | "integer" | "number" | "boolean" | "object" | "array";
+
+export interface Schema<T> {
+  readonly catalogType: CatalogType;
+  readonly description: string;
+  readonly required: boolean;
+  readonly defaultValue: T | undefined;
+  readonly fields?: Record<string, Schema<unknown>>;
+  readonly item?: Schema<unknown>;
+  parse(value: unknown, path?: string): T;
+}
+
+export type InferSchema<TSchema extends Schema<unknown>> = TSchema extends Schema<infer T>
+  ? T
+  : never;
+
+export interface SchemaOptions<T> {
+  description?: string;
+  required?: boolean;
+  default?: T;
+}
+
+const integerPattern = /^[+-]?\d+$/;
+const numberPattern = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+function withMeta<T>(
+  catalogType: CatalogType,
+  parser: (value: unknown, path: string) => T,
+  options?: SchemaOptions<T>,
+): Schema<T> {
+  const description = options?.description?.trim() ?? "";
+  const hasDefault = options ? Object.prototype.hasOwnProperty.call(options, "default") : false;
+  const defaultValue = hasDefault ? cloneValue(options?.default) : undefined;
+  const required = options?.required ?? !hasDefault;
+
+  return {
+    catalogType,
+    description,
+    required,
+    defaultValue,
+    parse(value: unknown, path = "$") {
+      if (value === undefined || value === null) {
+        if (hasDefault) {
+          return cloneValue(defaultValue) as T;
+        }
+        if (!required) {
+          return undefined as T;
+        }
+        throw new TypeError(`${path} is required`);
+      }
+      return parser(value, path);
+    },
+  };
+}
+
+export function string(options?: SchemaOptions<string>): Schema<string> {
+  return withMeta(
+    "string",
+    (value, path) => {
+      if (typeof value === "string") {
+        return value;
+      }
+      throw new TypeError(`${path} must be a string`);
+    },
+    options,
+  );
+}
+
+export function integer(options?: SchemaOptions<number>): Schema<number> {
+  return withMeta(
+    "integer",
+    (value, path) => {
+      if (typeof value === "number" && Number.isInteger(value)) {
+        return value;
+      }
+      if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (integerPattern.test(trimmed)) {
+          return Number.parseInt(trimmed, 10);
+        }
+      }
+      throw new TypeError(`${path} must be an integer`);
+    },
+    options,
+  );
+}
+
+export function number(options?: SchemaOptions<number>): Schema<number> {
+  return withMeta(
+    "number",
+    (value, path) => {
+      if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+      }
+      if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (numberPattern.test(trimmed)) {
+          const parsed = Number.parseFloat(trimmed);
+          if (Number.isFinite(parsed)) {
+            return parsed;
+          }
+        }
+      }
+      throw new TypeError(`${path} must be a number`);
+    },
+    options,
+  );
+}
+
+export function boolean(options?: SchemaOptions<boolean>): Schema<boolean> {
+  return withMeta(
+    "boolean",
+    (value, path) => {
+      if (typeof value === "boolean") {
+        return value;
+      }
+      if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "true" || normalized === "1") {
+          return true;
+        }
+        if (normalized === "false" || normalized === "0") {
+          return false;
+        }
+      }
+      throw new TypeError(`${path} must be a boolean`);
+    },
+    options,
+  );
+}
+
+export function array<T>(item: Schema<T>, options?: SchemaOptions<T[]>): Schema<T[]> {
+  const base = withMeta<T[]>(
+    "array",
+    (value, path) => {
+      if (!Array.isArray(value)) {
+        throw new TypeError(`${path} must be an array`);
+      }
+      return value.map((entry, index) => item.parse(entry, `${path}[${index}]`));
+    },
+    options,
+  );
+
+  return {
+    ...base,
+    item,
+  };
+}
+
+export function object<T extends Record<string, unknown>>(
+  fields: { [K in keyof T]: Schema<T[K]> },
+  options?: SchemaOptions<T>,
+): Schema<T> {
+  const base = withMeta<T>(
+    "object",
+    (value, path) => {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${path} must be an object`);
+      }
+      const source = value as Record<string, unknown>;
+      const output: Record<string, unknown> = {};
+      for (const [key, field] of Object.entries(fields)) {
+        const parsed = field.parse(source[key], `${path}.${key}`);
+        if (parsed !== undefined) {
+          output[key] = parsed;
+        }
+      }
+      return output as T;
+    },
+    options,
+  );
+
+  return {
+    ...base,
+    fields: fields as Record<string, Schema<unknown>>,
+  };
+}
+
+export function optional<T>(schema: Schema<T>): Schema<T | undefined> {
+  const wrapped: Schema<T | undefined> = {
+    catalogType: schema.catalogType,
+    description: schema.description,
+    required: false,
+    defaultValue: schema.defaultValue,
+    parse(value, path = "$") {
+      if (value === undefined || value === null) {
+        if (schema.defaultValue !== undefined) {
+          return cloneValue(schema.defaultValue);
+        }
+        return undefined;
+      }
+      return schema.parse(value, path);
+    },
+  };
+  const fields = schema.fields;
+  const item = schema.item;
+  return {
+    ...wrapped,
+    ...(fields !== undefined ? { fields } : {}),
+    ...(item !== undefined ? { item } : {}),
+  };
+}
+
+export const s = {
+  string,
+  integer,
+  number,
+  boolean,
+  array,
+  object,
+  optional,
+};
+
+function cloneValue<T>(value: T): T {
+  if (value === undefined) {
+    return value;
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/secrets.ts

@@ -0,0 +1,36 @@
+import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+import type { MaybePromise } from "./api.ts";
+
+export interface SecretsProviderOptions extends RuntimeProviderOptions {
+  getSecret: (name: string) => MaybePromise<string>;
+}
+
+export class SecretsProvider extends RuntimeProvider {
+  readonly kind = "secrets" as const;
+
+  private readonly getSecretHandler: SecretsProviderOptions["getSecret"];
+
+  constructor(options: SecretsProviderOptions) {
+    super(options);
+    this.getSecretHandler = options.getSecret;
+  }
+
+  async getSecret(name: string): Promise<string> {
+    return await this.getSecretHandler(name);
+  }
+}
+
+export function defineSecretsProvider(options: SecretsProviderOptions): SecretsProvider {
+  return new SecretsProvider(options);
+}
+
+export function isSecretsProvider(value: unknown): value is SecretsProvider {
+  return (
+    value instanceof SecretsProvider ||
+    (typeof value === "object" &&
+      value !== null &&
+      "kind" in value &&
+      (value as { kind?: unknown }).kind === "secrets" &&
+      "getSecret" in value)
+  );
+}

package/src/target.ts

@@ -0,0 +1,192 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, normalize, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { slugName, type ProviderKind } from "./provider.ts";
+
+export type ModuleTarget = {
+  modulePath: string;
+  exportName?: string;
+};
+
+export type ProviderTarget = ModuleTarget & {
+  kind: ProviderKind;
+};
+
+export type PackageConfig = {
+  name?: string;
+  providerTarget?: ProviderTarget;
+};
+
+type PackageProviderConfig =
+  | string
+  | {
+      kind?: string;
+      target?: string;
+    };
+
+const EXTERNAL_PROVIDER_KIND_TOKENS = new Set<string>([
+  "plugin",
+  "integration",
+  "auth",
+  "cache",
+  "secrets",
+  "s3",
+  "telemetry",
+]);
+
+export function parseModuleTarget(target: string, label = "gestalt provider target"): ModuleTarget {
+  const [modulePathRaw, exportNameRaw] = target.split("#", 2);
+  const modulePath = modulePathRaw?.trim() ?? "";
+  const exportName = exportNameRaw?.trim() || undefined;
+
+  if (!modulePath) {
+    throw new Error(`${label} must include a relative module path`);
+  }
+  if (!modulePath.startsWith("./") && !modulePath.startsWith("../")) {
+    throw new Error(`${label} module path must be relative`);
+  }
+  if (exportName !== undefined && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(exportName)) {
+    throw new Error(`${label} export must be a valid JavaScript identifier`);
+  }
+
+  const parsed: ModuleTarget = {
+    modulePath,
+  };
+  if (exportName !== undefined) {
+    parsed.exportName = exportName;
+  }
+  return parsed;
+}
+
+export function parseProviderTarget(target: string | PackageProviderConfig): ProviderTarget {
+  if (typeof target === "string") {
+    const prefixed = parseKindPrefixedTarget(target);
+    if (prefixed) {
+      return prefixed;
+    }
+    return {
+      kind: "integration",
+      ...parseModuleTarget(target, "gestalt.provider"),
+    };
+  }
+
+  const kind = parseProviderKind(target.kind ?? "integration");
+  if (!target.target || typeof target.target !== "string") {
+    throw new Error("gestalt.provider.target is required");
+  }
+  return {
+    kind,
+    ...parseModuleTarget(target.target, "gestalt.provider.target"),
+  };
+}
+
+export const parsePluginTarget = parseModuleTarget;
+
+export function readPackageConfig(root: string): PackageConfig {
+  const packagePath = resolve(root, "package.json");
+  const raw = JSON.parse(readFileSync(packagePath, "utf8")) as Record<string, unknown>;
+  const gestalt = (raw.gestalt ?? {}) as Record<string, unknown>;
+  const name = typeof raw.name === "string" ? raw.name.trim() : undefined;
+
+  let providerTarget: ProviderTarget | undefined;
+  if (typeof gestalt.provider === "string") {
+    providerTarget = parseProviderTarget(gestalt.provider);
+  } else if (isProviderConfigObject(gestalt.provider)) {
+    providerTarget = parseProviderTarget(gestalt.provider);
+  } else if (typeof gestalt.plugin === "string") {
+    providerTarget = {
+      kind: "integration",
+      ...parseModuleTarget(gestalt.plugin, "gestalt.plugin"),
+    };
+  }
+
+  const config: PackageConfig = {};
+  if (name !== undefined) {
+    config.name = name;
+  }
+  if (providerTarget !== undefined) {
+    config.providerTarget = providerTarget;
+  }
+  return config;
+}
+
+export function readPackageProviderTarget(root: string): ProviderTarget {
+  const config = readPackageConfig(root);
+  if (!config.providerTarget) {
+    throw new Error("package.json gestalt.provider or gestalt.plugin is required");
+  }
+  return config.providerTarget;
+}
+
+export function readPackagePluginTarget(root: string): string {
+  const target = readPackageProviderTarget(root);
+  if (target.kind !== "integration") {
+    throw new Error(`package.json provider kind ${JSON.stringify(target.kind)} is not an integration provider`);
+  }
+  return formatModuleTarget(target);
+}
+
+export function defaultProviderName(root: string): string {
+  const config = readPackageConfig(root);
+  return slugName(config.name ?? "");
+}
+
+export const defaultPluginName = defaultProviderName;
+
+export function resolveProviderModulePath(root: string, target: ProviderTarget | ModuleTarget): string {
+  const absolute = resolve(root, target.modulePath);
+  if (!isAbsolute(absolute)) {
+    throw new Error("provider module path did not resolve to an absolute path");
+  }
+  return normalize(absolute);
+}
+
+export const resolvePluginModulePath = resolveProviderModulePath;
+
+export function resolveProviderImportUrl(root: string, target: ProviderTarget | ModuleTarget): string {
+  return pathToFileURL(resolveProviderModulePath(root, target)).href;
+}
+
+export const resolvePluginImportUrl = resolveProviderImportUrl;
+
+export function formatProviderTarget(target: ProviderTarget): string {
+  return `${formatProviderKind(target.kind)}:${formatModuleTarget(target)}`;
+}
+
+export function formatModuleTarget(target: ModuleTarget): string {
+  return `${target.modulePath}${target.exportName ? `#${target.exportName}` : ""}`;
+}
+
+function parseKindPrefixedTarget(target: string): ProviderTarget | undefined {
+  const match = target.match(/^(plugin|integration|auth|cache|secrets|s3|telemetry):(.*)$/);
+  if (!match) {
+    return undefined;
+  }
+  return {
+    kind: parseProviderKind(match[1]!),
+    ...parseModuleTarget(match[2]!, "provider target"),
+  };
+}
+
+function parseProviderKind(value: string): ProviderKind {
+  const normalized = value.trim().toLowerCase();
+  if (!EXTERNAL_PROVIDER_KIND_TOKENS.has(normalized)) {
+    throw new Error(`unsupported provider kind ${JSON.stringify(value)}`);
+  }
+  if (normalized === "plugin") {
+    return "integration";
+  }
+  return normalized as ProviderKind;
+}
+
+function formatProviderKind(kind: ProviderKind): string {
+  if (kind === "integration") {
+    return "plugin";
+  }
+  return kind;
+}
+
+function isProviderConfigObject(value: unknown): value is { kind?: string; target?: string } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": [
+      "bun"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "gen/**/*.ts"
+  ]
+}