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

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

@@ -5,36 +5,100 @@ import { ListItemsConfig, ListItemsResults } from "../../../../common/SearchType
  * The errors that can be thrown by a {@link DataItemDBDriver}.
  * */
 export declare enum DATA_ITEM_DB_DRIVER_ERRORS {
+    /**
+     * Missing identifier value for the operation.
+     */
     MISSING_ID = "MISSING_ID",
+    /**
+     * Cursor value is invalid or malformed.
+     */
     INVALID_CURSOR = "INVALID_CURSOR",
+    /**
+     * Requested item was not found.
+     */
     ITEM_NOT_FOUND = "ITEM_NOT_FOUND",
+    /**
+     * Missing unique identifier for an update/delete.
+     */
     MISSING_UNIQUE_IDENTIFIER = "MISSING_UNIQUE_IDENTIFIER",
+    /**
+     * Search operator is not supported by the driver.
+     */
     SEARCH_COMPARISON_OPERATOR_NOT_SUPPORTED = "SEARCH_COMPARISON_OPERATOR_NOT_SUPPORTED"
 }
 /**
  * The generic type for a database driver configuration.
  * */
 export type DataItemDBDriverConfig<ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType> = {
+    /**
+     * Backing table or collection name.
+     */
     tableName: string;
+    /**
+     * Field name used as the unique identifier.
+     */
     uniquelyIdentifyingFieldName: UniquelyIdentifyingFieldName;
+    /**
+     * Optional identifier generator for new items.
+     */
     generateUniqueIdentifier?: (targetItem: ItemType) => string;
+    /**
+     * Optional DB-specific configuration payload.
+     */
     dbSpecificConfig?: Record<string, any>;
 };
 /**
  * The API for a database driver.
  * */
 export type DataItemDBDriver<ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType> = {
+    /**
+     * Create a new item in the data store.
+     * @param newItem New item payload without the identifying field.
+     * @returns Generated identifier for the created item.
+     */
     createItem: (newItem: Partial<Omit<ItemType, UniquelyIdentifyingFieldName>>) => Promise<ItemType[UniquelyIdentifyingFieldName]>;
+    /**
+     * Read an item from the data store.
+     * @param uniqueIdentifier Unique identifier value for the item.
+     * @param selectedFields Optional fields to select from the item.
+     * @returns Item payload (partial when selected fields are used).
+     */
     readItem: (uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName], selectedFields?: (keyof ItemType)[]) => Promise<Partial<ItemType>>;
+    /**
+     * Update an item in the data store.
+     * @param uniqueIdentifier Unique identifier value for the item.
+     * @param updatedItem Partial update payload for the item.
+     * @returns True when the item was updated.
+     */
     updateItem: (uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName], updatedItem: Partial<ItemType>) => Promise<boolean>;
+    /**
+     * Delete an item from the data store.
+     * @param uniqueIdentifier Unique identifier value for the item.
+     * @returns True when the item was deleted.
+     */
     deleteItem: (uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName]) => Promise<boolean>;
+    /**
+     * List items from the data store.
+     * @param config List configuration and criteria.
+     * @param selectedFields Optional fields to select from each item.
+     * @returns List results with items and cursor.
+     */
     listItems: (config: ListItemsConfig, selectedFields?: (keyof ItemType)[]) => Promise<ListItemsResults<Partial<ItemType>>>;
 };
 /**
  * An entry for a supported database driver.
  * */
 export type SupportedDataItemDBDriverEntry = {
+    /**
+     * Factory function for creating a driver instance.
+     * @param config Driver configuration.
+     * @returns Driver instance.
+     */
     factory: <ItemType extends Record<any, any>, UniquelyIdentifyingFieldName extends keyof ItemType>(config: DataItemDBDriverConfig<ItemType, UniquelyIdentifyingFieldName>) => DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>;
+    /**
+     * Return type info describing the DB-specific config.
+     * @returns Type info pack for DB-specific config.
+     */
     getDBSpecificConfigTypeInfo: () => TypeInfoPack;
 };
 /**
@@ -45,33 +109,89 @@ export type ItemRelationshipDBDriver = DataItemDBDriver<ItemRelationshipInfo, It
  * The location information for a file.
  * */
 export type BaseFileLocationInfo = {
+    /**
+     * Optional directory path for the file.
+     */
     directory?: string;
+    /**
+     * File name portion.
+     */
     name: string;
 };
 /**
  * The most integral information about a file.
  * */
 export type BaseFile = BaseFileLocationInfo & {
+    /**
+     * Last updated timestamp in milliseconds.
+     */
     updatedOn: number;
+    /**
+     * MIME type for the file.
+     */
     mimeType: string;
+    /**
+     * File size in bytes.
+     */
     sizeInBytes: number;
+    /**
+     * True when the item represents a directory.
+     */
     isDirectory?: boolean;
+    /**
+     * Optional signed upload URL.
+     */
     uploadUrl?: string;
+    /**
+     * Optional signed download URL.
+     */
     downloadUrl?: string;
 };
 /**
  * The result returned when listing files.
  * */
 export type ListFilesResult = {
+    /**
+     * Cursor string for pagination.
+     */
     cursor?: string;
+    /**
+     * Files returned in the page.
+     */
     files: BaseFile[];
 };
 /**
  * An API for a cloud file service driver.
  * */
 export type CloudFileServiceDriver = {
+    /**
+     * Get a signed URL for uploading a file.
+     * @param file File location info.
+     * @param baseDirectory Optional base directory prefix.
+     * @returns Signed upload URL.
+     */
     getFileUploadUrl: (file: BaseFileLocationInfo, baseDirectory?: string) => Promise<string>;
+    /**
+     * Get a signed URL for downloading a file.
+     * @param file File location info.
+     * @param baseDirectory Optional base directory prefix.
+     * @returns Signed download URL.
+     */
     getFileDownloadUrl: (file: BaseFileLocationInfo, baseDirectory?: string) => Promise<string>;
+    /**
+     * Delete a file.
+     * @param file File location info.
+     * @param baseDirectory Optional base directory prefix.
+     * @returns Promise resolved once deleted.
+     */
     deleteFile: (file: BaseFileLocationInfo, baseDirectory?: string) => Promise<void>;
+    /**
+     * List files in a directory.
+     * @param path Optional path prefix to list within.
+     * @param baseDirectory Optional base directory prefix.
+     * @param maxNumberOfFiles Maximum number of files to return.
+     * @param cursor Optional cursor string for pagination.
+     * @returns File list and cursor.
+     */
     listFiles: (path?: string, baseDirectory?: string, maxNumberOfFiles?: number, cursor?: string) => Promise<ListFilesResult>;
 };

package/api/ORM/drivers/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./S3FileItemDBDriver";
+export * from "./DynamoDBDataItemDBDriver";
+export * from "./InMemoryDataItemDBDriver";
+export * from "./InMemoryItemRelationshipDBDriver";
+export * from "./InMemoryFileItemDBDriver";
+export * from "./IndexingRelationshipDriver";
+export * from "./common";

package/api/ORM/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ORM exports for TypeInfo-based services and supporting utilities.
+ * */
+export * from "./drivers";
+export * from "./TypeInfoORMService";
+export * from "./DACUtils";
+export * from "./ORMRouteMap";

package/api/ORM/indexing/criteriaToStructuredWhere.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * Map {@link SearchCriteria} to structured-index {@link Where} clauses.
+ * Unsupported operators throw {@link TypeInfoORMServiceError}.
+ */
+import { SearchCriteria } from "../../../common/SearchTypes";
+import type { Where } from "../../Indexing/structured/Types";
+/**
+ * Translate {@link SearchCriteria.fieldCriteria} into a structured WHERE tree.
+ * @returns Structured where clause or undefined when no criteria exist.
+ */
+export declare const criteriaToStructuredWhere: (
+/**
+ * Search criteria to translate.
+ */
+criteria?: SearchCriteria) => Where | undefined;

package/api/Router/AWS.d.ts

@@ -0,0 +1,80 @@
+import { AuthInfo, CloudFunctionEventTransformer } from "./Types";
+/**
+ * AWS specific utilities for processing routing and normalizing Cloud Function events.
+ * */
+export declare namespace AWS {
+    /**
+     * An AWS specific Cloud Function event.
+     * */
+    interface IAWSCloudFunctionEvent {
+        /**
+         * AWS request context containing authorizer info and identity details.
+         */
+        requestContext?: Record<any, any>;
+        /**
+         * HTTP method for the incoming request.
+         */
+        httpMethod?: string;
+        /**
+         * Single-value HTTP headers.
+         */
+        headers?: Record<string, string>;
+        /**
+         * Multi-value HTTP headers keyed by header name.
+         */
+        multiValueHeaders?: Record<string, string[]>;
+        /**
+         * Request path string as provided by the AWS event.
+         */
+        path?: string;
+        /**
+         * Raw request body string (usually JSON).
+         */
+        body?: string;
+    }
+    /**
+     * @returns Normalized request path string.
+     */
+    const getPathFromEvent: (
+    /**
+     * AWS Cloud Function event to read the path from.
+     */
+    event: IAWSCloudFunctionEvent) => string;
+    /**
+     * @returns Parsed body payload, or undefined if parsing fails.
+     */
+    const getBodyFromEvent: (
+    /**
+     * AWS Cloud Function event to parse the body from.
+     */
+    event: IAWSCloudFunctionEvent) => any;
+    /**
+     * @returns Normalized headers keyed by lowercase header name.
+     */
+    const getHeadersFromEvent: (
+    /**
+     * AWS Cloud Function event to read headers from.
+     */
+    event: IAWSCloudFunctionEvent) => Record<string, string[]>;
+    /**
+     * @returns HTTP method string for the request.
+     */
+    const getMethodFromEvent: (
+    /**
+     * AWS Cloud Function event to read the method from.
+     */
+    event: IAWSCloudFunctionEvent) => string;
+    /**
+     * @returns Normalized auth info with user id and roles.
+     */
+    const getAuthInfo: (
+    /**
+     * AWS Cloud Function event to extract auth info from.
+     */
+    event: IAWSCloudFunctionEvent) => AuthInfo;
+    /**
+     * Parse out the Auth, CORS, Headers, Method and Body from an AWS Cloud Function event.
+     * @returns Normalized event data for routing.
+     * */
+    const normalizeCloudFunctionEvent: CloudFunctionEventTransformer;
+}

package/api/Router/Auth.d.ts

@@ -0,0 +1,14 @@
+import { AuthInfo, RouteAuthConfig } from "./Types";
+/**
+ * Resolve authorization for a request using auth info and route config.
+ * @returns True when the request is authorized.
+ * */
+export declare const getRouteIsAuthorized: (
+/**
+ * Auth info resolved for the incoming request.
+ */
+authInfo: AuthInfo, 
+/**
+ * Route-level auth requirements for the request.
+ */
+authConfig: RouteAuthConfig) => boolean;

package/api/Router/CORS.d.ts

@@ -0,0 +1,66 @@
+import { CORSPatter } from "./Types";
+/**
+ * Check origin equality against an allowed string.
+ * @returns True when the origin exactly matches the string.
+ * */
+export declare const originMatchesString: (
+/**
+ * Origin value from the request.
+ */
+origin?: string, 
+/**
+ * Allowed origin string to compare against.
+ */
+str?: string) => boolean;
+/**
+ * Check origin match against an allowed regular expression.
+ * @returns True when the origin matches the pattern.
+ * */
+export declare const originMatchesRegExp: (
+/**
+ * Origin value from the request.
+ */
+origin?: string, 
+/**
+ * Allowed origin pattern to test against.
+ */
+regExp?: RegExp) => boolean;
+/**
+ * Check an origin against a string or regex CORS pattern.
+ * @returns True when the origin matches the allowed pattern.
+ * */
+export declare const originMatches: (
+/**
+ * Origin value from the request.
+ */
+origin?: string, 
+/**
+ * Allowed origin matcher (string equality or regex test).
+ */
+corsPattern?: CORSPatter) => boolean;
+/**
+ * Resolve the origin if it is allowed by the CORS patterns.
+ * @returns The origin if allowed, otherwise an empty string.
+ * */
+export declare const getAllowedCORSOrigin: (
+/**
+ * Origin value from the request.
+ */
+origin?: string, 
+/**
+ * Allowed origin matchers to check.
+ */
+corsPatterns?: CORSPatter[]) => string;
+/**
+ * Build CORS response headers for a given origin and allow list.
+ * @returns CORS headers for the response.
+ * */
+export declare const getHeadersWithCORS: (
+/**
+ * Origin value from the request.
+ */
+origin?: string, 
+/**
+ * Allowed origin matchers to check.
+ */
+corsPatterns?: CORSPatter[]) => Record<string, string>;

package/{src/api → api}/Router/Types.d.ts

@@ -7,65 +7,131 @@ export type CORSPatter = string | RegExp;
  * Typically, from Cognito.
  * */
 export type AuthInfo = {
+    /**
+     * Unique user identifier from the auth provider.
+     */
     userId?: string;
+    /**
+     * Role or group names assigned to the user.
+     */
     roles?: string[];
 };
 /**
  * The normalized event data that is passed to the route handler.
  * */
 export type NormalizedCloudFunctionEventData = {
+    /**
+     * Auth info resolved from the incoming event.
+     */
     authInfo: AuthInfo;
+    /**
+     * Normalized headers keyed by lowercase header name.
+     */
     headers: Record<string, string[]>;
+    /**
+     * HTTP method (e.g. GET, POST).
+     */
     method: string;
+    /**
+     * Request path string.
+     */
     path: string;
+    /**
+     * Parsed body payload passed to handlers.
+     */
     body: any;
 };
 /**
  * The response information that sent back to the requester.
  * */
 export type CloudFunctionResponse = {
+    /**
+     * HTTP status code to return.
+     */
     statusCode: number;
+    /**
+     * Headers to include in the response.
+     */
     headers: Record<string, string>;
+    /**
+     * Serialized response payload.
+     */
     body: string;
 };
 /**
  * A function that handles an RPC request to a route.
- * */
+ * @param args Handler arguments derived from the normalized event body.
+ * @returns Handler result or a promise of the result.
+ */
 export type RouteHandler = (...args: any[]) => any | Promise<any>;
 /**
  * A factory for creating a route handler with context injected.
- * */
+ * @param eventData Normalized event data used to build the handler.
+ * @returns Route handler with context applied.
+ */
 export type RouteHandlerFactory = (eventData: NormalizedCloudFunctionEventData) => RouteHandler;
 /**
  * A configuration to specify the authentication required to access a route.
  * */
 export type RouteAuthConfig = {
+    /**
+     * When true, the route is publicly accessible without auth.
+     */
     public?: boolean;
+    /**
+     * When true, any authenticated user is allowed.
+     */
     anyAuthorized?: boolean;
+    /**
+     * Explicit list of role names permitted to access the route.
+     */
     allowedRoles?: string[];
 };
 /**
  * A configuration used to define how an RPC request to a specific path is handled.
  * */
 export type Route = {
+    /**
+     * Route path segment used as the lookup key in a RouteMap.
+     */
     path: string;
+    /**
+     * Optional auth requirements for the route.
+     */
     authConfig?: RouteAuthConfig;
 } & ({
+    /**
+     * Factory for building a handler with injected context.
+     */
     handlerFactory: RouteHandlerFactory;
     handler?: never;
 } | {
     handlerFactory?: never;
+    /**
+     * Direct handler invoked with the normalized body payload.
+     */
     handler: RouteHandler;
 });
 /**
  * A collection of {@link Route} objects, indexed by their path.
+ *
+ * @category Routing
  * */
 export type RouteMap = Record<string, Route>;
 /**
  * A function that transforms an event into a normalized event data object.
- * */
+ * @param event Raw cloud function event object.
+ * @returns Normalized event data for routing.
+ */
 export type CloudFunctionEventTransformer = (event: any) => NormalizedCloudFunctionEventData;
 /**
  * A function that routes an event to a route handler based on a {@link RouteMap}.
- * */
+ * @param event Raw cloud function event object.
+ * @param eventTransformer Transformer used to normalize the event.
+ * @param routeMap Route lookup map keyed by path.
+ * @param allowedOrigins Allowed origins for CORS responses.
+ * @param errorShouldBeExposedToClient Optional error filter for response payloads.
+ * @param debug When true, log handler inputs and outputs.
+ * @returns Cloud function response object.
+ */
 export type CloudFunctionEventRouter = (event: any, eventTransformer: CloudFunctionEventTransformer, routeMap: RouteMap, allowedOrigins: CORSPatter[], errorShouldBeExposedToClient?: (error: unknown) => boolean, debug?: boolean) => Promise<CloudFunctionResponse>;

package/api/Router/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @packageDocumentation
+ *
+ * Minimal Cloud Function routing helpers. Compose a {@link RouteMap}, wire in
+ * auth via {@link getRouteIsAuthorized}, apply CORS helpers, and dispatch with
+ * {@link handleCloudFunctionEvent}. AWS event normalization is available under
+ * {@link AWS}.
+ *
+ * Example wiring:
+ * ```ts
+ * import { AWS, addRoutesToRouteMap, handleCloudFunctionEvent } from "./Router";
+ * import type { RouteMap } from "./Router/Types";
+ *
+ * const routes: RouteMap = addRoutesToRouteMap({}, [
+ *   { path: "status", authConfig: { public: true }, handler: () => "ok" },
+ * ]);
+ *
+ * export const handler = (event: unknown) =>
+ *   handleCloudFunctionEvent(
+ *     event,
+ *     AWS.normalizeCloudFunctionEvent,
+ *     routes,
+ *     ["https://example.com"],
+ *   );
+ * ```
+ */
+import { CloudFunctionEventRouter, Route, RouteMap } from "./Types";
+export * from "./Types";
+export * from "./AWS";
+/**
+ * A utility function to add a route to a route map by path.
+ * @returns New route map with the route appended.
+ * */
+export declare const addRouteToRouteMap: (
+/**
+ * Existing route map to append to.
+ */
+routeMap: RouteMap, 
+/**
+ * Route definition to add to the map.
+ */
+route: Route, 
+/**
+ * Optional base path prefix to apply to the route path.
+ */
+basePath?: string) => RouteMap;
+/**
+ * Add multiple routes to a {@link RouteMap} by path.
+ *
+ * @category Routing
+ * @returns New route map with all routes appended.
+ * */
+export declare const addRoutesToRouteMap: (
+/**
+ * Existing route map to append to.
+ */
+routeMap: RouteMap, 
+/**
+ * Route list to add to the map.
+ */
+routes: Route[], 
+/**
+ * Optional base path prefix applied to all route paths.
+ */
+basePath?: string) => RouteMap;
+/**
+ * Apply one {@link RouteMap} to another.
+ * @returns New route map with the incoming routes merged.
+ * */
+export declare const addRouteMapToRouteMap: (
+/**
+ * Existing route map to append to.
+ */
+routeMap: RouteMap, 
+/**
+ * Route map to merge into the existing map.
+ */
+routeMapToAdd: RouteMap, 
+/**
+ * Optional base path prefix applied to all incoming paths.
+ */
+basePath?: string) => RouteMap;
+/**
+ * A Cloud Function event router.
+ *
+ * @category Routing
+ * @returns Cloud function response for the routed request.
+ * */
+export declare const handleCloudFunctionEvent: CloudFunctionEventRouter;

package/api/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @packageDocumentation
+ *
+ * Server-side API utilities: routing, ORM, indexing, and data access control.
+ *
+ * Import from the API subpath only:
+ * ```ts
+ * import {
+ *   AWS,
+ *   addRoutesToRouteMap,
+ *   handleCloudFunctionEvent,
+ *   type CloudFunctionResponse,
+ * } from "@resistdesign/voltra/api";
+ * ```
+ *
+ * @example
+ * ```ts
+ * import {
+ *   AWS,
+ *   addRoutesToRouteMap,
+ *   handleCloudFunctionEvent,
+ *   type CloudFunctionResponse,
+ * } from "@resistdesign/voltra/api";
+ *
+ * const routes = addRoutesToRouteMap({}, [
+ *   {
+ *     path: "",
+ *     authConfig: { anyAuthorized: true },
+ *     handler: async () => "WELCOME!!!!",
+ *   },
+ * ]);
+ *
+ * export const handler = async (
+ *   event: any,
+ * ): Promise<CloudFunctionResponse> =>
+ *   handleCloudFunctionEvent(
+ *     event,
+ *     AWS.normalizeCloudFunctionEvent,
+ *     routes,
+ *     [
+ *       process.env.CLIENT_ORIGIN as string,
+ *       /https:\\/\\/example\\.com(:.*?$|\\/.*$|$)/gim,
+ *     ],
+ *   );
+ * ```
+ *
+ * See also: `@resistdesign/voltra/app` for client-side app helpers.
+ */
+/**
+ * @category api
+ * @group Indexing
+ */
+export * from "./Indexing";
+/**
+ * @category api
+ * @group ORM
+ */
+export * from "./ORM";
+/**
+ * @category api
+ * @group Routing
+ */
+export * from "./Router";
+/**
+ * @category api
+ * @group Data Access Control
+ */
+export * from "./DataAccessControl";