@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/api/ORM/drivers/S3FileItemDBDriver/ConfigTypes.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Trace function signature for client logging.
+ */
+export type Trace = (...content: any[]) => void;
+/**
+ * Logger interface for S3 client config.
+ */
+export type Logger = {
+    /**
+     * Optional trace output or trace level string.
+     */
+    trace?: string | Trace;
+    /**
+     * Debug logger.
+     */
+    debug: Trace;
+    /**
+     * Info logger.
+     */
+    info: Trace;
+    /**
+     * Warn logger.
+     */
+    warn: Trace;
+    /**
+     * Error logger.
+     */
+    error: Trace;
+};
+/**
+ * Endpoint definition for S3 client config.
+ */
+export type Endpoint = {
+    /**
+     * Protocol scheme (e.g., https).
+     */
+    protocol: string;
+    /**
+     * Hostname for the endpoint.
+     */
+    hostname: string;
+    /**
+     * Optional port override.
+     */
+    port?: string;
+    /**
+     * Path portion of the endpoint URL.
+     */
+    path: string;
+    /**
+     * Optional query string.
+     */
+    query?: string;
+};
+/**
+ * Auth scheme properties wrapper.
+ */
+export type Properties = {
+    /**
+     * Auth scheme identifiers.
+     */
+    authSchemes?: string;
+};
+/**
+ * Retry strategy wrapper for S3 client config.
+ */
+export type RetryStrategy = {
+    /**
+     * Strategy mode identifier.
+     */
+    mode?: string;
+    /**
+     * Retry strategy implementation.
+     */
+    retry: any;
+};
+/**
+ * Credentials configuration for S3 client.
+ */
+export type Credentials = {
+    /**
+     * Access key id.
+     */
+    accessKeyId: string;
+    /**
+     * Secret access key.
+     */
+    secretAccessKey: string;
+    /**
+     * Optional session token.
+     */
+    sessionToken?: string;
+    /**
+     * Optional credential scope.
+     */
+    credentialScope?: string;
+    /**
+     * Optional expiration timestamp string.
+     */
+    expiration?: string;
+};
+/**
+ * Signer interface wrapper for S3 client.
+ */
+export type Signer = {
+    /**
+     * Sign function implementation.
+     */
+    sign: any;
+};
+/**
+ * S3 client configuration subset for generated docs.
+ */
+export type AbridgedS3ClientConfig = {
+    /**
+     * Custom request handler override.
+     */
+    requestHandler?: string;
+    /**
+     * API version override for the S3 client.
+     */
+    apiVersion?: string;
+    /**
+     * Hash implementation identifier.
+     */
+    sha256?: string;
+    /**
+     * URL parser override.
+     */
+    urlParser?: string;
+    /**
+     * Body length checker override.
+     */
+    bodyLengthChecker?: string;
+    /**
+     * Stream collector override.
+     */
+    streamCollector?: string;
+    /**
+     * Base64 decoder override.
+     */
+    base64Decoder?: string;
+    /**
+     * Base64 encoder override.
+     */
+    base64Encoder?: string;
+    /**
+     * UTF-8 decoder override.
+     */
+    utf8Decoder?: string;
+    /**
+     * UTF-8 encoder override.
+     */
+    utf8Encoder?: string;
+    /**
+     * Runtime identifier override.
+     */
+    runtime?: string;
+    /**
+     * Disable host prefix injection.
+     */
+    disableHostPrefix?: string | false | true;
+    /**
+     * Service id override.
+     */
+    serviceId?: string;
+    /**
+     * Enable dualstack endpoints.
+     */
+    useDualstackEndpoint?: string | false | true;
+    /**
+     * Enable FIPS endpoints.
+     */
+    useFipsEndpoint?: string | false | true;
+    /**
+     * AWS region identifier.
+     */
+    region?: string;
+    /**
+     * Credential provider override.
+     */
+    credentialDefaultProvider?: string;
+    /**
+     * Signing path escape toggle.
+     */
+    signingEscapePath?: string | false | true;
+    /**
+     * Use ARN region in requests.
+     */
+    useArnRegion?: string | false | true;
+    /**
+     * Default user agent provider override.
+     */
+    defaultUserAgentProvider?: string;
+    /**
+     * Stream hasher override.
+     */
+    streamHasher?: string;
+    /**
+     * MD5 implementation override.
+     */
+    md5?: string;
+    /**
+     * SHA1 implementation override.
+     */
+    sha1?: string;
+    /**
+     * AWS chunked encoding stream override.
+     */
+    getAwsChunkedEncodingStream?: string;
+    /**
+     * Maximum retry attempts.
+     */
+    maxAttempts?: string;
+    /**
+     * Retry mode identifier.
+     */
+    retryMode?: string;
+    /**
+     * Logger configuration or identifier.
+     */
+    logger?: string | Logger;
+    /**
+     * Extensions applied to the client.
+     */
+    extensions?: string;
+    eventStreamSerdeProvider?: string;
+    /**
+     * Defaults mode selector for AWS SDK config.
+     * @allowCustomSelection
+     */
+    defaultsMode?: "standard" | "in-region" | "cross-region" | "mobile" | "auto" | "legacy";
+    /**
+     * SDK stream mixin override.
+     */
+    sdkStreamMixin?: string;
+    /**
+     * Explicit endpoint override.
+     */
+    endpoint?: string | Endpoint;
+    /**
+     * Endpoint provider override.
+     */
+    endpointProvider?: string;
+    /**
+     * TLS usage override.
+     */
+    tls?: string | false | true;
+    /**
+     * Retry strategy override.
+     */
+    retryStrategy?: string | RetryStrategy;
+    /**
+     * Credentials override.
+     */
+    credentials?: string | Credentials;
+    /**
+     * Signer override.
+     */
+    signer?: string | Signer;
+    /**
+     * System clock offset override.
+     */
+    systemClockOffset?: string;
+    /**
+     * Signing region override.
+     */
+    signingRegion?: string;
+    /**
+     * Signer constructor override.
+     */
+    signerConstructor?: string;
+    /**
+     * Force path-style addressing.
+     */
+    forcePathStyle?: string | false | true;
+    /**
+     * Use accelerate endpoint.
+     */
+    useAccelerateEndpoint?: string | false | true;
+    /**
+     * Disable multiregion access points.
+     */
+    disableMultiregionAccessPoints?: string | false | true;
+    /**
+     * Follow region redirects.
+     */
+    followRegionRedirects?: string | false | true;
+    /**
+     * S3 Express identity provider override.
+     */
+    s3ExpressIdentityProvider?: string;
+    /**
+     * Custom user agent string.
+     */
+    customUserAgent?: string;
+    /**
+     * Use global endpoint.
+     */
+    useGlobalEndpoint?: string | false | true;
+    /**
+     * Disable S3 Express session auth.
+     */
+    disableS3ExpressSessionAuth?: string | false | true;
+};
+/**
+ * Configuration overrides for the S3 file driver.
+ */
+export type S3SpecificConfig = {
+    /**
+     * S3 client configuration overrides.
+     */
+    s3Config?: AbridgedS3ClientConfig;
+    /**
+     * S3 bucket name for file storage.
+     */
+    bucketName: string;
+    /**
+     * Optional URL expiration time in seconds.
+     */
+    urlExpirationInSeconds?: number;
+};

package/api/ORM/drivers/S3FileItemDBDriver/S3FileDriver.d.ts

@@ -0,0 +1,118 @@
+import { S3, S3ClientConfig } from "@aws-sdk/client-s3";
+import { BaseFile, BaseFileLocationInfo, CloudFileServiceDriver } from "../common/Types";
+/**
+ * Error codes for S3 file driver operations.
+ */
+export declare const S3_FILE_DRIVER_ERRORS: {
+    /**
+     * File path contains invalid segments.
+     */
+    INVALID_PATH: string;
+};
+/**
+ * Build a full S3 object key for a file.
+ * @param file File location info.
+ * @param baseDirectory Optional base directory prefix.
+ * @returns Full object key for the file.
+ */
+export declare const getFullFileKey: ({ file, baseDirectory, }: {
+    file: BaseFileLocationInfo;
+    baseDirectory?: string;
+}) => string;
+/**
+ * Parse a full key into file location info.
+ * @param path Full object key path.
+ * @returns Base file location info.
+ */
+export declare const getBaseFileLocationInfo: (path: string) => BaseFileLocationInfo;
+/**
+ * The configuration for an {@link S3FileDriver}.
+ * */
+export type S3FileDriverConfig = {
+    /**
+     * Optional S3 client configuration.
+     */
+    s3Config?: S3ClientConfig;
+    /**
+     * S3 bucket name for file storage.
+     */
+    bucketName: string;
+    /**
+     * Optional URL expiration time in seconds.
+     */
+    urlExpirationInSeconds?: number;
+};
+/**
+ * Use S3 as a {@link CloudFileServiceDriver} for {@link BaseFile}s.
+ */
+export declare class S3FileDriver implements CloudFileServiceDriver {
+    protected config: S3FileDriverConfig;
+    protected s3: S3;
+    /**
+     * @param config Driver configuration including S3 client and bucket settings.
+     */
+    constructor(config: S3FileDriverConfig);
+    /**
+     * Get a signed URL for uploading a file.
+     * @returns Signed URL for uploading the file.
+     */
+    getFileUploadUrl: (
+    /**
+     * File location info for the upload.
+     */
+    file: BaseFileLocationInfo, 
+    /**
+     * Optional base directory prefix.
+     */
+    baseDirectory?: string) => Promise<string>;
+    /**
+     * Get a signed URL for downloading a file.
+     * @returns Signed URL for downloading the file.
+     */
+    getFileDownloadUrl: (
+    /**
+     * File location info for the download.
+     */
+    file: BaseFileLocationInfo, 
+    /**
+     * Optional base directory prefix.
+     */
+    baseDirectory?: string) => Promise<string>;
+    /**
+     * Delete a file.
+     * @returns Promise resolved once the file is deleted.
+     */
+    deleteFile: (
+    /**
+     * File location info to delete.
+     */
+    file: BaseFileLocationInfo, 
+    /**
+     * Optional base directory prefix.
+     */
+    baseDirectory?: string) => Promise<void>;
+    /**
+     * List the files and directories in a directory.
+     * @returns File list and cursor.
+     */
+    listFiles: (
+    /**
+     * Optional path prefix to list within.
+     */
+    path?: string, 
+    /**
+     * Optional base directory prefix.
+     */
+    baseDirectory?: string, 
+    /**
+     * Maximum number of files to return.
+     */
+    maxNumberOfFiles?: number, 
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string) => Promise<{
+        files: BaseFile[];
+        cursor: string | undefined;
+    }>;
+}

package/{src/api → api}/ORM/drivers/S3FileItemDBDriver.d.ts

@@ -1,8 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * S3-backed file item driver that exposes files as ORM items with upload/download URLs.
+ */
 import { S3 } from "@aws-sdk/client-s3";
 import { BaseFile, CloudFileServiceDriver, DataItemDBDriver, DataItemDBDriverConfig, SupportedDataItemDBDriverEntry } from "./common/Types";
 import { S3SpecificConfig } from "./S3FileItemDBDriver/ConfigTypes";
 import { ListItemsConfig } from "../../../common/SearchTypes";
+/**
+ * ORM file item with id plus base file fields.
+ */
 export type BaseFileItem = {
+    /**
+     * File identifier (full key).
+     */
     id: string;
 } & BaseFile;
 /**
@@ -13,25 +24,41 @@ export declare class S3FileItemDBDriver implements DataItemDBDriver<BaseFileItem
     protected specificConfig: S3SpecificConfig;
     protected s3: S3;
     protected s3FileDriver: CloudFileServiceDriver;
+    /**
+     * @param config Driver configuration including S3 settings.
+     */
     constructor(config: DataItemDBDriverConfig<BaseFileItem, "id">);
     /**
      * Create a new @{@link BaseFileItem}.
+     * @param item New file item payload without the id field.
+     * @returns Generated file id.
      * */
     createItem: (item: Partial<Omit<BaseFileItem, "id">>) => Promise<string>;
     /**
      * Read a @{@link BaseFileItem} by its id.
+     * @param id Unique identifier value for the file.
+     * @param selectFields Optional fields to select from the file item.
+     * @returns File item payload (partial when selected fields are used).
      * */
     readItem: (id: string, selectFields?: (keyof BaseFileItem)[]) => Promise<BaseFileItem>;
     /**
      * Update a @{@link BaseFileItem}.
+     * @param uniqueIdentifier Unique identifier value for the file.
+     * @param item Partial update payload for the file.
+     * @returns True when the item was updated.
      * */
     updateItem: (uniqueIdentifier: BaseFileItem["id"], item: Partial<BaseFileItem>) => Promise<boolean>;
     /**
      * Delete a @{@link BaseFileItem} by its id.
+     * @param id Unique identifier value for the file.
+     * @returns True when the item was deleted.
      */
     deleteItem: (id: string) => Promise<boolean>;
     /**
      * List @{@link BaseFileItem}s by a given criteria.
+     * @param config List configuration and criteria.
+     * @param selectFields Optional fields to select from each file item.
+     * @returns List results with items and cursor.
      */
     listItems: (config: ListItemsConfig, selectFields?: (keyof BaseFileItem)[]) => Promise<{
         items: Partial<BaseFileItem>[];

package/api/ORM/drivers/common/SupportedTypeInfoORMDBDrivers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @packageDocumentation
+ *
+ * Registry of supported Type Info ORM drivers and their selection guidance.
+ *
+ * Selection notes:
+ * - DynamoDB is the default for production item storage with predictable scale.
+ * - In-memory drivers are best for tests and ephemeral local workflows.
+ * - S3 file drivers are intended for blob/file persistence with key-based access.
+ */
+import { SupportedDataItemDBDriverEntry } from "./Types";
+/**
+ * The supported Type Info ORM DB driver names.
+ * */
+export declare enum SupportedTypeInfoORMDBDriverNames {
+    /**
+     * DynamoDB-backed data item driver.
+     */
+    DYNAMO_DB_DATA_ITEM = "DYNAMO_DB_DATA_ITEM",
+    /**
+     * In-memory data item driver.
+     */
+    IN_MEMORY_DATA_ITEM = "IN_MEMORY_DATA_ITEM",
+    /**
+     * In-memory file item driver.
+     */
+    IN_MEMORY_FILE_ITEM = "IN_MEMORY_FILE_ITEM",
+    /**
+     * S3-backed file item driver.
+     */
+    S3_FILE_ITEM = "S3_FILE_ITEM"
+}
+/**
+ * A map of supported Type Info ORM DB drivers by name.
+ * */
+export declare const SUPPORTED_TYPE_INFO_ORM_DB_DRIVERS: Record<SupportedTypeInfoORMDBDriverNames, SupportedDataItemDBDriverEntry>;