@distilled.cloud/core 0.0.0-john

package/lib/traits.d.ts

@@ -0,0 +1,274 @@
+import * as AST from "effect/SchemaAST";
+/**
+ * Internal symbol for annotation metadata storage.
+ */
+declare const annotationMetaSymbol: unique symbol;
+/**
+ * Any type that has an .annotate() method returning itself.
+ * This includes Schema.Schema and Schema.PropertySignature.
+ */
+type Annotatable = {
+    annotate(annotations: unknown): Annotatable;
+};
+/**
+ * An Annotation is a callable that can be used with .pipe() AND
+ * has symbol properties so it works directly with Schema.Struct/Class.
+ *
+ * The index signatures allow TypeScript to accept this as a valid annotations object.
+ */
+export interface Annotation {
+    <A extends Annotatable>(schema: A): A;
+    readonly [annotationMetaSymbol]: Array<{
+        symbol: symbol;
+        value: unknown;
+    }>;
+    readonly [key: symbol]: unknown;
+    readonly [key: string]: unknown;
+}
+/**
+ * Create an annotation builder for a given symbol and value.
+ * This is the core primitive used to build all trait annotations.
+ */
+export declare function makeAnnotation<T>(sym: symbol, value: T): Annotation;
+/**
+ * Combine multiple annotations into one.
+ * Use when you need multiple annotations on the same schema.
+ *
+ * @example
+ * ```ts
+ * const MyInput = Schema.Struct({
+ *   id: Schema.String.pipe(T.all(T.PathParam(), T.Required())),
+ * });
+ * ```
+ */
+export declare function all(...annotations: Annotation[]): Annotation;
+/** Symbol for HTTP operation metadata (method + path template) */
+export declare const httpSymbol: unique symbol;
+/** HTTP method type */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+/** HTTP trait configuration */
+export interface HttpTrait {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Path template with {param} placeholders */
+    path: string;
+    /** Content type override (e.g., "multipart") */
+    contentType?: string;
+    /** Whether the request has a body (used by GCP generator) */
+    hasBody?: boolean;
+}
+/**
+ * Http trait - defines the HTTP method and path template for an operation.
+ * Path parameters are specified using {paramName} syntax.
+ *
+ * @example
+ * ```ts
+ * const GetDatabaseInput = Schema.Struct({
+ *   organization: Schema.String.pipe(T.PathParam()),
+ *   database: Schema.String.pipe(T.PathParam()),
+ * }).pipe(
+ *   T.Http({ method: "GET", path: "/organizations/{organization}/databases/{database}" })
+ * );
+ * ```
+ */
+export declare const Http: (trait: HttpTrait) => Annotation;
+/** Symbol for path parameter annotation */
+export declare const pathParamSymbol: unique symbol;
+/**
+ * PathParam trait - marks a field as a path parameter.
+ * The field name is used as the placeholder name in the path template.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   organization: Schema.String.pipe(T.PathParam()),
+ * }).pipe(
+ *   T.Http({ method: "GET", path: "/organizations/{organization}" })
+ * );
+ * ```
+ */
+export declare const PathParam: () => Annotation;
+/** Symbol for query parameter annotation */
+export declare const queryParamSymbol: unique symbol;
+/**
+ * QueryParam trait - marks a field as a query parameter.
+ * Optionally specify a different wire name.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   perPage: Schema.optional(Schema.Number).pipe(T.QueryParam("per_page")),
+ * });
+ * ```
+ */
+export declare const QueryParam: (name?: string | undefined) => Annotation;
+/** Symbol for header parameter annotation */
+export declare const headerParamSymbol: unique symbol;
+/**
+ * HeaderParam trait - marks a field as a header parameter.
+ * Specify the header name.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   apiToken: Schema.String.pipe(T.HeaderParam("X-API-Token")),
+ * });
+ * ```
+ */
+export declare const HeaderParam: (name: string) => Annotation;
+/**
+ * HttpPath - alias for PathParam that also carries the wire name.
+ * Used in generated code: `Schema.String.pipe(T.HttpPath("account_id"))`
+ */
+export declare const HttpPath: (name: string) => Annotation;
+/**
+ * HttpQuery - alias for QueryParam with an explicit wire name.
+ * Used in generated code: `Schema.optional(Schema.String).pipe(T.HttpQuery("per_page"))`
+ */
+export declare const HttpQuery: (name: string) => Annotation;
+/**
+ * HttpHeader - alias for HeaderParam.
+ * Used in generated code: `Schema.String.pipe(T.HttpHeader("X-Custom-Header"))`
+ */
+export declare const HttpHeader: (name: string) => Annotation;
+/** Symbol for HTTP body annotation */
+export declare const httpBodySymbol: unique symbol;
+/**
+ * HttpBody - marks a field as the raw HTTP body.
+ * Used for operations where a field IS the entire request body
+ * (not a named field within a JSON body).
+ */
+export declare const HttpBody: () => Annotation;
+/** Symbol for response body path transformation */
+export declare const responsePathSymbol: unique symbol;
+/**
+ * ResponsePath - decode the response from a nested path within the raw body.
+ * Useful for providers that wrap successful responses in envelopes like
+ * `{ result: <payload>, result_info: ... }`.
+ */
+export declare const ResponsePath: (path: string) => Annotation;
+/** Symbol for form data file annotation */
+export declare const httpFormDataFileSymbol: unique symbol;
+/**
+ * HttpFormDataFile - marks a field as a file upload in multipart form data.
+ */
+export declare const HttpFormDataFile: () => Annotation;
+/** Symbol for API error code mapping */
+export declare const apiErrorCodeSymbol: unique symbol;
+/**
+ * ApiErrorCode trait - maps an error class to an API error code.
+ * Used to match API error responses to typed error classes.
+ *
+ * @example
+ * ```ts
+ * class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()(
+ *   "NotFoundError",
+ *   { message: Schema.String },
+ * ).pipe(T.ApiErrorCode("not_found")) {}
+ * ```
+ */
+export declare const ApiErrorCode: (code: string) => Annotation;
+/** Symbol for service metadata */
+export declare const serviceSymbol: unique symbol;
+/** Service metadata */
+export interface ServiceTrait {
+    name: string;
+    version?: string;
+    baseUrl?: string;
+    /** GCP-specific: Root URL for the service */
+    rootUrl?: string;
+    /** GCP-specific: Service path appended to root URL */
+    servicePath?: string;
+    /** Allow additional properties for provider-specific metadata */
+    [key: string]: unknown;
+}
+/**
+ * Service trait - attaches service metadata to a schema.
+ */
+export declare const Service: (trait: ServiceTrait) => Annotation;
+/**
+ * Get annotation value from an AST node, following encoding chain if needed.
+ */
+export declare const getAnnotation: <T>(ast: AST.AST, symbol: symbol) => T | undefined;
+/**
+ * Get HTTP trait from a schema's AST.
+ */
+export declare const getHttpTrait: (ast: AST.AST) => HttpTrait | undefined;
+export declare const getResponsePath: (ast: AST.AST) => string | undefined;
+/**
+ * Check if a PropertySignature has the pathParam annotation.
+ * Works for both PathParam() (annotation value = true) and HttpPath("wire_name") (annotation value = string).
+ */
+export declare const isPathParam: (prop: AST.PropertySignature) => boolean;
+/**
+ * Get query param name from a PropertySignature (returns true if unnamed, string if named).
+ */
+export declare const getQueryParam: (prop: AST.PropertySignature) => string | boolean | undefined;
+/**
+ * Get header param name from a PropertySignature.
+ */
+export declare const getHeaderParam: (prop: AST.PropertySignature) => string | undefined;
+/**
+ * Get API error code from an error class AST.
+ */
+export declare const getApiErrorCode: (ast: AST.AST) => string | undefined;
+/**
+ * Get service metadata from a schema's AST.
+ */
+export declare const getServiceTrait: (ast: AST.AST) => ServiceTrait | undefined;
+/**
+ * Extract path parameters from a schema's struct properties.
+ * Returns an array of field names that have the PathParam annotation.
+ */
+export declare const getPathParams: (ast: AST.AST) => string[];
+/**
+ * Build the request path by substituting path parameters into the template.
+ * Simple version that assumes input keys match template placeholders.
+ * For schema-aware path building (with camelCase → wire_name mapping), use buildPathFromSchema.
+ */
+export declare const buildPath: (template: string, input: Record<string, unknown>) => string;
+/**
+ * Extract AST property signatures from a schema AST, following encoding chain and suspends.
+ */
+export declare const getStructProps: (ast: AST.AST) => AST.PropertySignature[];
+/**
+ * Get the path parameter wire name from a PropertySignature.
+ * - For HttpPath("wire_name"), returns the wire name string.
+ * - For PathParam(), returns the property name (since annotation is `true`).
+ * - Returns undefined if not a path param.
+ */
+export declare const getPathParamWireName: (prop: AST.PropertySignature) => string | undefined;
+/**
+ * Result of categorizing a schema's input properties by their HTTP binding.
+ */
+export interface RequestParts {
+    /** Resolved path with all parameters substituted */
+    path: string;
+    /** Query parameters: wire_name → string value */
+    query: Record<string, string | string[]>;
+    /** Header parameters: header-name → string value */
+    headers: Record<string, string>;
+    /** Body: remaining non-path/query/header properties, with wire-name keys where applicable */
+    body: Record<string, unknown> | undefined;
+    /** Whether the body should use multipart/form-data */
+    isMultipart: boolean;
+}
+/**
+ * Schema-aware request builder. Categorizes input properties into path, query, header,
+ * and body parts using annotations on the schema AST.
+ *
+ * Handles camelCase → wire_name mapping for path params (HttpPath), query params (HttpQuery),
+ * and header params (HttpHeader).
+ *
+ * When `inputSchema` is provided, uses `Schema.encodeSync` to encode the input through the
+ * schema's encoding pipeline (e.g., `encodeKeys` for camelCase → snake_case mapping).
+ * The encoded output is used for body construction, ensuring wire-format key names.
+ */
+export declare const buildRequestParts: (ast: AST.AST, httpTrait: HttpTrait, input: Record<string, unknown>, inputSchema?: any) => RequestParts;
+/**
+ * Helper to get a value from an object using a dot-separated path.
+ * Used for pagination traits and nested property access.
+ */
+export declare const getPath: (obj: unknown, path: string) => unknown;
+export {};
+//# sourceMappingURL=traits.d.ts.map

package/lib/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"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"}