@valon-technologies/gestalt 0.0.1-alpha.8 → 0.0.1-alpha.9

package/src/s3.ts

@@ -28,12 +28,18 @@ const ENV_S3_SOCKET = "GESTALT_S3_SOCKET";
 const WRITE_CHUNK_SIZE = 64 * 1024;
 const textEncoder = new TextEncoder();
 
+/**
+ * Returns the environment variable name used to discover an S3 socket.
+ */
 export function s3SocketEnv(name?: string): string {
   const trimmed = name?.trim() ?? "";
   if (!trimmed) return ENV_S3_SOCKET;
   return `${ENV_S3_SOCKET}_${trimmed.replace(/[^A-Za-z0-9]/g, "_").toUpperCase()}`;
 }
 
+/**
+ * Error returned when an object reference does not exist.
+ */
 export class S3NotFoundError extends Error {
   constructor(message?: string) {
     super(message ?? "s3: not found");
@@ -41,6 +47,9 @@ export class S3NotFoundError extends Error {
   }
 }
 
+/**
+ * Error returned when conditional read or write preconditions fail.
+ */
 export class S3PreconditionFailedError extends Error {
   constructor(message?: string) {
     super(message ?? "s3: precondition failed");
@@ -48,6 +57,9 @@ export class S3PreconditionFailedError extends Error {
   }
 }
 
+/**
+ * Error returned when the requested byte range is invalid.
+ */
 export class S3InvalidRangeError extends Error {
   constructor(message?: string) {
     super(message ?? "s3: invalid range");
@@ -55,12 +67,18 @@ export class S3InvalidRangeError extends Error {
   }
 }
 
+/**
+ * Identifies a concrete object or object version.
+ */
 export interface ObjectRef {
   bucket: string;
   key: string;
   versionId?: string;
 }
 
+/**
+ * Metadata returned for an S3 object.
+ */
 export interface ObjectMeta {
   ref: ObjectRef;
   etag: string;
@@ -71,11 +89,17 @@ export interface ObjectMeta {
   storageClass: string;
 }
 
+/**
+ * Byte range for partial object reads.
+ */
 export interface ByteRange {
   start?: number | bigint;
   end?: number | bigint;
 }
 
+/**
+ * Conditional and range options for reads.
+ */
 export interface ReadOptions {
   range?: ByteRange;
   ifMatch?: string;
@@ -84,6 +108,9 @@ export interface ReadOptions {
   ifUnmodifiedSince?: Date;
 }
 
+/**
+ * Optional headers and conditions for writes.
+ */
 export interface WriteOptions {
   contentType?: string;
   cacheControl?: string;
@@ -95,6 +122,9 @@ export interface WriteOptions {
   ifNoneMatch?: string;
 }
 
+/**
+ * Listing options for object pagination and prefix filtering.
+ */
 export interface ListOptions {
   bucket: string;
   prefix?: string;
@@ -104,6 +134,9 @@ export interface ListOptions {
   maxKeys?: number;
 }
 
+/**
+ * Single page of results returned by {@link S3.listObjects}.
+ */
 export interface ListPage {
   objects: ObjectMeta[];
   commonPrefixes: string[];
@@ -111,11 +144,17 @@ export interface ListPage {
   hasMore: boolean;
 }
 
+/**
+ * Conditional options for server-side copy operations.
+ */
 export interface CopyOptions {
   ifMatch?: string;
   ifNoneMatch?: string;
 }
 
+/**
+ * Supported presign methods.
+ */
 export enum PresignMethod {
   Get = "GET",
   Put = "PUT",
@@ -123,6 +162,9 @@ export enum PresignMethod {
   Head = "HEAD",
 }
 
+/**
+ * Options used when generating a presigned URL.
+ */
 export interface PresignOptions {
   method?: PresignMethod;
   expiresSeconds?: number | bigint;
@@ -131,6 +173,9 @@ export interface PresignOptions {
   headers?: Record<string, string>;
 }
 
+/**
+ * Result returned by {@link S3.presignObject} or {@link S3Object.presign}.
+ */
 export interface PresignResult {
   url: string;
   method: PresignMethod;
@@ -138,6 +183,9 @@ export interface PresignResult {
   headers: Record<string, string>;
 }
 
+/**
+ * Accepted write body sources for the S3 client.
+ */
 export type S3BodySource =
   | string
   | Uint8Array
@@ -149,16 +197,25 @@ export type S3BodySource =
   | null
   | undefined;
 
+/**
+ * Streaming read result returned by the S3 client.
+ */
 export interface ReadResult {
   meta: ObjectMeta;
   stream: AsyncIterable<Uint8Array>;
 }
 
+/**
+ * Result returned by an authored S3 provider implementation.
+ */
 export interface ProviderReadResult {
   meta: ObjectMeta;
   body?: S3BodySource;
 }
 
+/**
+ * Runtime hooks required to implement a Gestalt S3 provider.
+ */
 export interface S3ProviderOptions extends RuntimeProviderOptions {
   headObject: (ref: ObjectRef) => MaybePromise<ObjectMeta>;
   readObject: (ref: ObjectRef, options?: ReadOptions) => MaybePromise<ProviderReadResult>;
@@ -180,6 +237,9 @@ export interface S3ProviderOptions extends RuntimeProviderOptions {
   ) => MaybePromise<PresignResult>;
 }
 
+/**
+ * S3 provider implementation consumed by the Gestalt runtime.
+ */
 export class S3Provider extends RuntimeProvider {
   readonly kind = "s3" as const;
 
@@ -239,10 +299,16 @@ export class S3Provider extends RuntimeProvider {
   }
 }
 
+/**
+ * Creates an S3 provider from standard object storage handlers.
+ */
 export function defineS3Provider(options: S3ProviderOptions): S3Provider {
   return new S3Provider(options);
 }
 
+/**
+ * Runtime type guard for S3 providers loaded from user modules.
+ */
 export function isS3Provider(value: unknown): value is S3Provider {
   return (
     value instanceof S3Provider ||
@@ -260,6 +326,11 @@ export function isS3Provider(value: unknown): value is S3Provider {
   );
 }
 
+/**
+ * Adapts an authored S3 provider to the shared protocol service implementation.
+ *
+ * @internal
+ */
 export function createS3Service(
   provider: S3Provider,
 ): Partial<ServiceImpl<typeof S3Service>> {
@@ -411,6 +482,17 @@ export function createS3Service(
   };
 }
 
+/**
+ * Client for invoking a host-provided S3 service over the Gestalt transport.
+ *
+ * @example
+ * ```ts
+ * import { S3 } from "@valon-technologies/gestalt";
+ *
+ * const s3 = new S3();
+ * await s3.object("example-bucket", "hello.json").writeJSON({ ok: true });
+ * ```
+ */
 export class S3 {
   private readonly client: Client<typeof S3Service>;
 
@@ -467,9 +549,10 @@ export class S3 {
     body?: S3BodySource,
     options?: WriteOptions,
   ): Promise<ObjectMeta> {
-    const snapshot = snapshotS3Body(body);
+    const byteBody = asS3ByteArray(body);
+    const preparedBody = byteBody ? cloneBytes(byteBody) : body;
     const response = await s3Rpc(() =>
-      this.client.writeObject(writeRequests(ref, snapshot, options)),
+      this.client.writeObject(writeRequests(ref, preparedBody, options)),
     );
     return fromProtoObjectMeta(response.meta);
   }
@@ -543,16 +626,25 @@ export class S3 {
   }
 }
 
+/**
+ * Convenience wrapper for working with a single S3 object reference.
+ */
 export class S3Object {
   constructor(
     private readonly client: S3,
     readonly ref: ObjectRef,
   ) {}
 
+  /**
+   * Loads object metadata without downloading the object body.
+   */
   async stat(): Promise<ObjectMeta> {
     return await this.client.headObject(this.ref);
   }
 
+  /**
+   * Returns `true` when the referenced object exists.
+   */
   async exists(): Promise<boolean> {
     try {
       await this.stat();
@@ -565,40 +657,67 @@ export class S3Object {
     }
   }
 
+  /**
+   * Reads an object and returns its metadata and byte stream.
+   */
   async read(options?: ReadOptions): Promise<ReadResult> {
     return await this.client.readObject(this.ref, options);
   }
 
+  /**
+   * Reads only the object byte stream.
+   */
   async stream(options?: ReadOptions): Promise<AsyncIterable<Uint8Array>> {
     const result = await this.read(options);
     return result.stream;
   }
 
+  /**
+   * Reads an object into memory as bytes.
+   */
   async bytes(options?: ReadOptions): Promise<Uint8Array> {
     const result = await this.read(options);
     return await collectBytes(result.stream);
   }
 
+  /**
+   * Reads an object into memory as a string.
+   */
   async text(options?: ReadOptions, encoding = "utf-8"): Promise<string> {
     return new TextDecoder(encoding).decode(await this.bytes(options));
   }
 
+  /**
+   * Reads and parses an object as JSON.
+   */
   async json<T = unknown>(options?: ReadOptions): Promise<T> {
     return JSON.parse(await this.text(options)) as T;
   }
 
+  /**
+   * Writes an object body to storage.
+   */
   async write(body?: S3BodySource, options?: WriteOptions): Promise<ObjectMeta> {
     return await this.client.writeObject(this.ref, body, options);
   }
 
+  /**
+   * Writes binary content to storage.
+   */
   async writeBytes(body: Uint8Array | ArrayBuffer | ArrayBufferView): Promise<ObjectMeta> {
     return await this.write(body);
   }
 
+  /**
+   * Writes string content to storage.
+   */
   async writeString(body: string, options?: WriteOptions): Promise<ObjectMeta> {
     return await this.write(body, options);
   }
 
+  /**
+   * Writes JSON content using `application/json` by default.
+   */
   async writeJSON(value: unknown, options: WriteOptions = {}): Promise<ObjectMeta> {
     return await this.write(JSON.stringify(value), {
       ...options,
@@ -606,10 +725,16 @@ export class S3Object {
     });
   }
 
+  /**
+   * Deletes the referenced object.
+   */
   async delete(): Promise<void> {
     await this.client.deleteObject(this.ref);
   }
 
+  /**
+   * Generates a presigned URL for the referenced object.
+   */
   async presign(options?: PresignOptions): Promise<PresignResult> {
     return await this.client.presignObject(this.ref, options);
   }
@@ -755,16 +880,9 @@ async function* toAsyncByteStream(body?: S3BodySource): AsyncIterable<Uint8Array
     yield* chunkBytes(textEncoder.encode(body));
     return;
   }
-  if (body instanceof Uint8Array) {
-    yield* chunkBytes(body);
-    return;
-  }
-  if (body instanceof ArrayBuffer) {
-    yield* chunkBytes(new Uint8Array(body));
-    return;
-  }
-  if (ArrayBuffer.isView(body)) {
-    yield* chunkBytes(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+  const bytes = asS3ByteArray(body);
+  if (bytes) {
+    yield* chunkBytes(bytes);
     return;
   }
   if (body instanceof Blob) {
@@ -790,20 +908,17 @@ function* chunkBytes(bytes: Uint8Array): Iterable<Uint8Array> {
   }
 }
 
-function snapshotS3Body(body?: S3BodySource): S3BodySource | undefined {
-  if (body == null || typeof body === "string") {
-    return body;
-  }
+function asS3ByteArray(body?: S3BodySource): Uint8Array | undefined {
   if (body instanceof Uint8Array) {
-    return cloneBytes(body);
+    return body;
   }
   if (body instanceof ArrayBuffer) {
-    return body.slice(0);
+    return new Uint8Array(body);
   }
   if (ArrayBuffer.isView(body)) {
-    return new Uint8Array(body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength));
+    return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
   }
-  return body;
+  return undefined;
 }
 
 async function* readableStreamToAsyncIterable(

package/src/schema.ts

@@ -1,5 +1,11 @@
+/**
+ * Catalog schema kinds supported by the TypeScript SDK.
+ */
 export type CatalogType = "string" | "integer" | "number" | "boolean" | "object" | "array";
 
+/**
+ * Runtime schema that validates operation input and output values.
+ */
 export interface Schema<T> {
   readonly catalogType: CatalogType;
   readonly description: string;
@@ -10,10 +16,16 @@ export interface Schema<T> {
   parse(value: unknown, path?: string): T;
 }
 
+/**
+ * Extracts the TypeScript type represented by a {@link Schema}.
+ */
 export type InferSchema<TSchema extends Schema<unknown>> = TSchema extends Schema<infer T>
   ? T
   : never;
 
+/**
+ * Shared options supported by all schema builders.
+ */
 export interface SchemaOptions<T> {
   description?: string;
   required?: boolean;
@@ -53,6 +65,9 @@ function withMeta<T>(
   };
 }
 
+/**
+ * Creates a string schema.
+ */
 export function string(options?: SchemaOptions<string>): Schema<string> {
   return withMeta(
     "string",
@@ -66,6 +81,9 @@ export function string(options?: SchemaOptions<string>): Schema<string> {
   );
 }
 
+/**
+ * Creates an integer schema.
+ */
 export function integer(options?: SchemaOptions<number>): Schema<number> {
   return withMeta(
     "integer",
@@ -85,6 +103,9 @@ export function integer(options?: SchemaOptions<number>): Schema<number> {
   );
 }
 
+/**
+ * Creates a floating-point or integer number schema.
+ */
 export function number(options?: SchemaOptions<number>): Schema<number> {
   return withMeta(
     "number",
@@ -107,6 +128,9 @@ export function number(options?: SchemaOptions<number>): Schema<number> {
   );
 }
 
+/**
+ * Creates a boolean schema that accepts `true` / `false` and `1` / `0`.
+ */
 export function boolean(options?: SchemaOptions<boolean>): Schema<boolean> {
   return withMeta(
     "boolean",
@@ -129,6 +153,9 @@ export function boolean(options?: SchemaOptions<boolean>): Schema<boolean> {
   );
 }
 
+/**
+ * Creates an array schema for repeated values.
+ */
 export function array<T>(item: Schema<T>, options?: SchemaOptions<T[]>): Schema<T[]> {
   const base = withMeta<T[]>(
     "array",
@@ -147,6 +174,19 @@ export function array<T>(item: Schema<T>, options?: SchemaOptions<T[]>): Schema<
   };
 }
 
+/**
+ * Creates an object schema from a field map.
+ *
+ * @example
+ * ```ts
+ * import { s } from "@valon-technologies/gestalt";
+ *
+ * const input = s.object({
+ *   name: s.string(),
+ *   excited: s.optional(s.boolean()),
+ * });
+ * ```
+ */
 export function object<T extends Record<string, unknown>>(
   fields: { [K in keyof T]: Schema<T[K]> },
   options?: SchemaOptions<T>,
@@ -176,6 +216,9 @@ export function object<T extends Record<string, unknown>>(
   };
 }
 
+/**
+ * Marks another schema as optional while preserving its metadata.
+ */
 export function optional<T>(schema: Schema<T>): Schema<T | undefined> {
   const wrapped: Schema<T | undefined> = {
     catalogType: schema.catalogType,
@@ -201,6 +244,9 @@ export function optional<T>(schema: Schema<T>): Schema<T | undefined> {
   };
 }
 
+/**
+ * Namespace-style schema builder helpers.
+ */
 export const s = {
   string,
   integer,

package/src/secrets.ts

@@ -1,10 +1,16 @@
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { MaybePromise } from "./api.ts";
 
+/**
+ * Runtime hooks required to implement a Gestalt secrets provider.
+ */
 export interface SecretsProviderOptions extends RuntimeProviderOptions {
   getSecret: (name: string) => MaybePromise<string>;
 }
 
+/**
+ * Secrets provider implementation consumed by the Gestalt runtime.
+ */
 export class SecretsProvider extends RuntimeProvider {
   readonly kind = "secrets" as const;
 
@@ -20,10 +26,16 @@ export class SecretsProvider extends RuntimeProvider {
   }
 }
 
+/**
+ * Creates a secrets provider from a simple `getSecret` implementation.
+ */
 export function defineSecretsProvider(options: SecretsProviderOptions): SecretsProvider {
   return new SecretsProvider(options);
 }
 
+/**
+ * Runtime type guard for secrets providers loaded from user modules.
+ */
 export function isSecretsProvider(value: unknown): value is SecretsProvider {
   return (
     value instanceof SecretsProvider ||