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

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

@@ -0,0 +1,229 @@
+/**
+ * Trace function signature for client logging.
+ */
+export type Trace = (...content: any[]) => void;
+/**
+ * Logger interface for DynamoDB 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 DynamoDB 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;
+};
+/**
+ * Retry strategy wrapper for DynamoDB client config.
+ */
+export type RetryStrategy = {
+    /**
+     * Strategy mode identifier.
+     */
+    mode?: string;
+    /**
+     * Retry strategy implementation.
+     */
+    retry: any;
+};
+/**
+ * DynamoDB client configuration subset for generated docs.
+ */
+export type DynamoDBSpecificConfig = {
+    /**
+     * Custom request handler override.
+     */
+    requestHandler?: string;
+    /**
+     * API version override for the DynamoDB 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;
+    /**
+     * Default user agent provider override.
+     */
+    defaultUserAgentProvider?: string;
+    /**
+     * AWS region identifier.
+     */
+    region?: string;
+    /**
+     * Credential provider override.
+     */
+    credentialDefaultProvider?: 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;
+    /**
+     * Defaults mode selector for AWS SDK config.
+     * @allowCustomSelection
+     */
+    defaultsMode?: "standard" | "in-region" | "cross-region" | "mobile" | "auto" | "legacy";
+    /**
+     * Endpoint discovery provider override.
+     */
+    endpointDiscoveryEnabledProvider?: 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;
+    /**
+     * Custom user agent string.
+     */
+    customUserAgent?: string;
+    /**
+     * HTTP auth schemes override.
+     */
+    httpAuthSchemes?: string;
+    /**
+     * HTTP auth scheme provider override.
+     */
+    httpAuthSchemeProvider?: string;
+    /**
+     * Credentials override.
+     */
+    credentials?: string;
+    /**
+     * Signer override.
+     */
+    signer?: string;
+    /**
+     * Signing path escape toggle.
+     */
+    signingEscapePath?: string | false | true;
+    /**
+     * System clock offset override.
+     */
+    systemClockOffset?: string;
+    /**
+     * Signing region override.
+     */
+    signingRegion?: string;
+    /**
+     * Signer constructor override.
+     */
+    signerConstructor?: string;
+    /**
+     * Endpoint cache size override.
+     */
+    endpointCacheSize?: string;
+    /**
+     * Enable endpoint discovery.
+     */
+    endpointDiscoveryEnabled?: string | false | true;
+};

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

@@ -0,0 +1,89 @@
+/**
+ * @packageDocumentation
+ *
+ * DynamoDB-backed data item driver for TypeInfo ORM. Supports CRUD and scan-based
+ * list operations with SearchCriteria filters.
+ */
+import { DataItemDBDriver, DataItemDBDriverConfig, SupportedDataItemDBDriverEntry } from "./common/Types";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { TypeInfoDataItem } from "../../../common/TypeParsing/TypeInfo";
+import { ListItemsConfig, ListItemsResults } from "../../../common/SearchTypes";
+/**
+ * A {@link DataItemDBDriver} that uses DynamoDB as its database.
+ * */
+export declare class DynamoDBDataItemDBDriver<ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType> implements DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName> {
+    /**
+     * Driver configuration including table name and DynamoDB config.
+     */
+    protected config: DataItemDBDriverConfig<ItemType, UniquelyIdentifyingFieldName>;
+    protected dynamoDBClient: DynamoDBClient;
+    /**
+     * @param config Driver configuration including DynamoDB client settings.
+     */
+    constructor(
+    /**
+     * Driver configuration including table name and DynamoDB config.
+     */
+    config: DataItemDBDriverConfig<ItemType, UniquelyIdentifyingFieldName>);
+    /**
+     * Create an item in the database.
+     * @returns Generated identifier for the created item.
+     */
+    createItem: (
+    /**
+     * New item payload without the identifying field.
+     */
+    newItem: Partial<Omit<ItemType, UniquelyIdentifyingFieldName>>) => Promise<ItemType[UniquelyIdentifyingFieldName]>;
+    /**
+     * Read an item from the database.
+     * @returns Item payload (partial when selected fields are used).
+     */
+    readItem: (
+    /**
+     * Unique identifier value for the item.
+     */
+    uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName], 
+    /**
+     * Optional fields to select from the item.
+     */
+    selectedFields?: (keyof ItemType)[]) => Promise<Partial<ItemType>>;
+    /**
+     * Update an item in the database.
+     * @returns True when an item was updated.
+     */
+    updateItem: (
+    /**
+     * Unique identifier value for the item.
+     */
+    uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName], 
+    /**
+     * Partial update payload for the item.
+     */
+    updatedItem: Partial<ItemType>) => Promise<boolean>;
+    /**
+     * Delete an item from the database.
+     * @returns True when an item was deleted.
+     */
+    deleteItem: (
+    /**
+     * Unique identifier value for the item.
+     */
+    uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName]) => Promise<boolean>;
+    /**
+     * List items from the database.
+     * @returns List results with items and cursor.
+     */
+    listItems: (
+    /**
+     * List configuration and criteria.
+     */
+    config: ListItemsConfig, 
+    /**
+     * Optional fields to select from each item.
+     */
+    selectedFields?: (keyof ItemType)[]) => Promise<ListItemsResults<ItemType>>;
+}
+/**
+ * The supported DB driver entry for the DynamoDB {@link DataItemDBDriver}.
+ * */
+export declare const DynamoDBSupportedDataItemDBDriverEntry: SupportedDataItemDBDriverEntry;

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

@@ -0,0 +1,4 @@
+/**
+ * In-memory driver config (intentionally empty).
+ */
+export type InMemorySpecificConfig = {};

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

@@ -0,0 +1,55 @@
+import { DataItemDBDriver, DataItemDBDriverConfig, SupportedDataItemDBDriverEntry } from "./common/Types";
+import type { TypeInfoDataItem } from "../../../common/TypeParsing/TypeInfo";
+import type { ListItemsConfig, ListItemsResults } from "../../../common/SearchTypes";
+/**
+ * In-memory data item driver for testing and local usage.
+ */
+export declare class InMemoryDataItemDBDriver<ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType> implements DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName> {
+    /**
+     * Driver configuration including table name and identifier settings.
+     */
+    protected config: DataItemDBDriverConfig<ItemType, UniquelyIdentifyingFieldName>;
+    private items;
+    constructor(
+    /**
+     * Driver configuration including table name and identifier settings.
+     */
+    config: DataItemDBDriverConfig<ItemType, UniquelyIdentifyingFieldName>);
+    /**
+     * Create a new item in memory.
+     * @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 memory.
+     * @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 memory.
+     * @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 memory.
+     * @param uniqueIdentifier Unique identifier value for the item.
+     * @returns True when the item was deleted.
+     */
+    deleteItem: (uniqueIdentifier: ItemType[UniquelyIdentifyingFieldName]) => Promise<boolean>;
+    /**
+     * List items from memory.
+     * @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<ItemType>>;
+}
+/**
+ * The supported DB driver entry for the in-memory {@link DataItemDBDriver}.
+ * */
+export declare const InMemorySupportedDataItemDBDriverEntry: SupportedDataItemDBDriverEntry;

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

@@ -0,0 +1,13 @@
+/**
+ * Configuration overrides for the in-memory file driver.
+ */
+export type InMemoryFileSpecificConfig = {
+    /**
+     * Prefix used when generating upload URLs.
+     */
+    uploadUrlPrefix?: string;
+    /**
+     * Prefix used when generating download URLs.
+     */
+    downloadUrlPrefix?: string;
+};

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

@@ -0,0 +1,98 @@
+import { DataItemDBDriver, DataItemDBDriverConfig, SupportedDataItemDBDriverEntry } from "./common/Types";
+import type { ListItemsConfig, ListItemsResults } from "../../../common/SearchTypes";
+import type { BaseFileItem } from "./S3FileItemDBDriver";
+/**
+ * Configuration overrides for the in-memory file driver.
+ */
+export type InMemoryFileSpecificConfig = {
+    /**
+     * Optional time source for updatedOn timestamps.
+     */
+    now?: () => number;
+    /**
+     * Prefix used when generating upload URLs.
+     */
+    uploadUrlPrefix?: string;
+    /**
+     * Prefix used when generating download URLs.
+     */
+    downloadUrlPrefix?: string;
+};
+/**
+ * In-memory file driver backed by local state.
+ */
+export declare class InMemoryFileItemDBDriver implements DataItemDBDriver<BaseFileItem, "id"> {
+    /**
+     * Driver configuration including table name and config overrides.
+     */
+    protected config: DataItemDBDriverConfig<BaseFileItem, "id">;
+    private items;
+    private aliases;
+    private readonly now;
+    private readonly uploadUrlPrefix;
+    private readonly downloadUrlPrefix;
+    constructor(
+    /**
+     * Driver configuration including table name and config overrides.
+     */
+    config: DataItemDBDriverConfig<BaseFileItem, "id">);
+    private resolveId;
+    private buildUrl;
+    /**
+     * Create a new file item in memory.
+     * @returns Generated file id.
+     */
+    createItem: (
+    /**
+     * New file item payload without the id field.
+     */
+    item: Partial<Omit<BaseFileItem, "id">>) => Promise<string>;
+    /**
+     * Read a file item from memory.
+     * @returns File item payload (partial when selected fields are used).
+     */
+    readItem: (
+    /**
+     * Unique identifier value for the file.
+     */
+    uniqueIdentifier: string, 
+    /**
+     * Optional fields to select from the file item.
+     */
+    selectFields?: (keyof BaseFileItem)[]) => Promise<Partial<BaseFileItem>>;
+    /**
+     * Update a file item in memory.
+     * @returns True when the item was updated.
+     */
+    updateItem: (
+    /**
+     * Unique identifier value for the file.
+     */
+    uniqueIdentifier: string, 
+    /**
+     * Partial update payload for the file.
+     */
+    item: Partial<BaseFileItem>) => Promise<boolean>;
+    /**
+     * Delete a file item from memory.
+     * @returns True when the item was deleted.
+     */
+    deleteItem: (id: string) => Promise<boolean>;
+    /**
+     * List file items from memory.
+     * @returns List results with items and cursor.
+     */
+    listItems: (
+    /**
+     * List configuration and criteria.
+     */
+    config: ListItemsConfig, 
+    /**
+     * Optional fields to select from each file item.
+     */
+    selectFields?: (keyof BaseFileItem)[]) => Promise<ListItemsResults<Partial<BaseFileItem>>>;
+}
+/**
+ * The supported DB driver entry for the in-memory file {@link DataItemDBDriver}.
+ * */
+export declare const InMemoryFileSupportedDataItemDBDriverEntry: SupportedDataItemDBDriverEntry;

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

@@ -0,0 +1,16 @@
+import { DataItemDBDriverConfig } from "./common/Types";
+import type { ItemRelationshipInfo, ItemRelationshipInfoIdentifyingKeys } from "../../../common/ItemRelationshipInfoTypes";
+import { InMemoryDataItemDBDriver } from "./InMemoryDataItemDBDriver";
+/**
+ * Configuration for the in-memory relationship driver.
+ */
+export type InMemoryItemRelationshipDBDriverConfig = DataItemDBDriverConfig<ItemRelationshipInfo, ItemRelationshipInfoIdentifyingKeys.id>;
+/**
+ * In-memory relationship driver using DataItem storage.
+ */
+export declare class InMemoryItemRelationshipDBDriver extends InMemoryDataItemDBDriver<ItemRelationshipInfo, ItemRelationshipInfoIdentifyingKeys.id> {
+    /**
+     * @param config Driver configuration for relationship items.
+     */
+    constructor(config: InMemoryItemRelationshipDBDriverConfig);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * @packageDocumentation
+ *
+ * Relationship driver that maps ORM relationship operations to the indexing
+ * relational backends (in-memory or DynamoDB).
+ */
+import { BaseItemRelationshipInfo, ItemRelationshipInfo } from "../../../common/ItemRelationshipInfoTypes";
+import { ListItemsResults, ListRelationshipsConfig } from "../../../common/SearchTypes";
+import type { Edge, EdgeKey, EdgePage, RelationalQueryOptions } from "../../Indexing/rel/Types";
+type EdgeMetadata = Record<string, unknown>;
+/**
+ * Relational backend interface for relationship edge operations.
+ */
+export type RelationalBackend<TMetadata extends EdgeMetadata = EdgeMetadata> = {
+    /**
+     * Insert or update an edge.
+     * @param edge Edge to store.
+     * @returns Promise resolved once stored.
+     */
+    putEdge(edge: Edge<TMetadata>): Promise<void> | void;
+    /**
+     * Remove an edge by key.
+     * @param key Edge key to remove.
+     * @returns Promise resolved once removed.
+     */
+    removeEdge(key: EdgeKey): Promise<void> | void;
+    /**
+     * Query outgoing edges for an entity and relation.
+     * @param fromId Source entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of outgoing edges.
+     */
+    getOutgoing(fromId: string, relation: string, options?: RelationalQueryOptions): Promise<EdgePage<TMetadata>> | EdgePage<TMetadata>;
+    /**
+     * Query incoming edges for an entity and relation.
+     * @param toId Target entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of incoming edges.
+     */
+    getIncoming(toId: string, relation: string, options?: RelationalQueryOptions): Promise<EdgePage<TMetadata>> | EdgePage<TMetadata>;
+};
+/**
+ * Configuration for the indexing relationship driver.
+ */
+export type IndexingRelationshipDriverConfig = {
+    /**
+     * Relational backend used for edge operations.
+     */
+    backend: RelationalBackend;
+    /**
+     * Resolver for relation name from type/field.
+     */
+    relationNameFor: (fromTypeName: string, fromTypeFieldName: string) => string;
+    /**
+     * Optional encoder for entity ids.
+     */
+    encodeEntityId?: (typeName: string, primaryFieldValue: string) => string;
+    /**
+     * Optional decoder for entity ids.
+     */
+    decodeEntityId?: (typeName: string, entityId: string) => string;
+};
+/**
+ * Adapter that stores relationships as directional edges via a relational backend.
+ */
+export declare class IndexingRelationshipDriver {
+    private readonly config;
+    private readonly encodeEntityId;
+    private readonly decodeEntityId;
+    /**
+     * @param config Driver configuration for relation indexing.
+     */
+    constructor(config: IndexingRelationshipDriverConfig);
+    private buildEdgeKey;
+    private buildRelationshipInfo;
+    private removeAllOutgoing;
+    /**
+     * Create a relationship via the relational backend.
+     * @returns Promise resolved once the relationship is stored.
+     */
+    createRelationship(
+    /**
+     * Relationship info to create.
+     */
+    relationship: BaseItemRelationshipInfo, 
+    /**
+     * Target type name for the relationship.
+     */
+    toTypeName: string, 
+    /**
+     * When true, remove existing outgoing edges before inserting.
+     */
+    ensureSingle: boolean): Promise<void>;
+    /**
+     * Delete a relationship via the relational backend.
+     * @returns Promise resolved once the relationship is removed.
+     */
+    deleteRelationship(
+    /**
+     * Relationship info to delete.
+     */
+    relationship: BaseItemRelationshipInfo, 
+    /**
+     * Target type name for the relationship.
+     */
+    toTypeName: string): Promise<void>;
+    /**
+     * List relationships via the relational backend.
+     * @returns List results with items and cursor.
+     */
+    listRelationships(
+    /**
+     * Relationship list configuration and origin.
+     */
+    config: ListRelationshipsConfig, 
+    /**
+     * Target type name for the relationship.
+     */
+    toTypeName: string): Promise<ListItemsResults<ItemRelationshipInfo>>;
+}
+export {};