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

package/api/DBX/DBXTypes.d.ts

@@ -0,0 +1,176 @@
+import type { AuthInfo, CORSPatter, RouteAuthConfig, RouteMap } from "../Router/Types";
+import type { DataItemDBDriver, DataItemDBDriverConfig, ItemRelationshipDBDriver } from "../ORM/drivers/common/Types";
+import type { TypeInfoDataItem, TypeInfoMap } from "../../common/TypeParsing/TypeInfo";
+import type { TypeInfoORMDACConfig, TypeInfoORMIndexingConfig } from "../ORM/TypeInfoORMService";
+/**
+ * Overrides for building in-memory item drivers per type.
+ */
+export type DBXDriverConfigOverrides = Partial<Omit<DataItemDBDriverConfig<TypeInfoDataItem, string>, "uniquelyIdentifyingFieldName">>;
+/**
+ * Configuration for constructing a DBX in-memory runtime.
+ */
+export type DBXRuntimeConfig = {
+    /**
+     * Type info map used to validate and shape items.
+     */
+    typeInfoMap: TypeInfoMap;
+    /**
+     * Optional list of type names to materialize as item drivers.
+     */
+    itemTypeNames?: string[];
+    /**
+     * Optional overrides for per-type driver configs.
+     */
+    driverConfigByType?: Record<string, DBXDriverConfigOverrides>;
+    /**
+     * Optional map of custom ID generators for item types.
+     */
+    idGeneratorsByType?: Record<string, (targetItem: TypeInfoDataItem) => string>;
+    /**
+     * Optional prebuilt drivers keyed by type name.
+     */
+    drivers?: Record<string, DataItemDBDriver<any, any>>;
+    /**
+     * Optional relationship driver to use when relation indexing is disabled.
+     */
+    relationshipDriver?: ItemRelationshipDBDriver;
+    /**
+     * Optional indexing configuration override.
+     */
+    indexing?: TypeInfoORMIndexingConfig;
+    /**
+     * When true (default), in-memory indexing backends are supplied.
+     */
+    useInMemoryIndexing?: boolean;
+    /**
+     * Base path prefix for ORM routes.
+     */
+    basePath?: string;
+    /**
+     * Route auth configuration for ORM routes.
+     */
+    authConfig?: RouteAuthConfig;
+    /**
+     * Allowed origins used to generate CORS headers.
+     */
+    allowedOrigins?: CORSPatter[];
+    /**
+     * Optional DAC configuration (excluding accessing role).
+     */
+    dacConfig?: TypeInfoORMDACConfig;
+    /**
+     * Optional accessor to resolve the accessing role id from auth info.
+     */
+    getAccessingRoleId?: (authInfo: AuthInfo) => string;
+    /**
+     * Optional predicate to decide whether errors are exposed.
+     */
+    errorShouldBeExposedToClient?: (error: unknown) => boolean;
+};
+/**
+ * Resolved DBX runtime dependencies for tests.
+ */
+export type DBXRuntime = {
+    /**
+     * Type info map used by the ORM service.
+     */
+    typeInfoMap: TypeInfoMap;
+    /**
+     * Base path prefix for ORM routes.
+     */
+    basePath: string;
+    /**
+     * Route map bound to the in-memory ORM service.
+     */
+    routeMap: RouteMap;
+    /**
+     * Allowed origins for CORS headers.
+     */
+    allowedOrigins: CORSPatter[];
+    /**
+     * Driver resolver for item types.
+     */
+    getDriver: (typeName: string) => DataItemDBDriver<any, any>;
+    /**
+     * Built driver instances keyed by type name.
+     */
+    drivers: Record<string, DataItemDBDriver<any, any>>;
+    /**
+     * Optional relationship driver used when relation indexing is off.
+     */
+    relationshipDriver?: ItemRelationshipDBDriver;
+    /**
+     * Indexing configuration used by the ORM service.
+     */
+    indexing?: TypeInfoORMIndexingConfig;
+    /**
+     * Optional auth config applied to ORM routes.
+     */
+    authConfig?: RouteAuthConfig;
+    /**
+     * Optional DAC configuration excluding accessing role.
+     */
+    dacConfig?: TypeInfoORMDACConfig;
+    /**
+     * Optional accessor to resolve the accessing role id from auth info.
+     */
+    getAccessingRoleId?: (authInfo: AuthInfo) => string;
+    /**
+     * Optional predicate to decide whether errors are exposed.
+     */
+    errorShouldBeExposedToClient?: (error: unknown) => boolean;
+};
+/**
+ * Input payload for a DBX router request.
+ */
+export type DBXRequestInput = {
+    /**
+     * HTTP method for the request.
+     */
+    method: string;
+    /**
+     * Route path segment, relative to the DBX base path.
+     */
+    path: string;
+    /**
+     * Arguments passed to the handler (body array).
+     */
+    args?: any[];
+    /**
+     * Optional body payload (used when args are omitted).
+     */
+    body?: any;
+    /**
+     * Optional headers to include on the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional auth info for the request.
+     */
+    auth?: AuthInfo;
+    /**
+     * Optional origin header value.
+     */
+    origin?: string;
+};
+/**
+ * Parsed response returned by the DBX request runner.
+ */
+export type DBXResponse<T = unknown> = {
+    /**
+     * HTTP status code returned by the router.
+     */
+    statusCode: number;
+    /**
+     * Response headers returned by the router.
+     */
+    headers: Record<string, string>;
+    /**
+     * Raw response body string.
+     */
+    body: string;
+    /**
+     * Parsed response body when JSON parsing succeeds.
+     */
+    parsedBody?: T;
+};

package/api/DBX/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DBX testing utilities and helpers.
+ */
+export * from "./DBXAsserts";
+export * from "./DBXRequest";
+export * from "./DBXRuntime";
+export * from "./DBXSeed";
+export * from "./DBXTypes";

package/api/DataAccessControl.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @packageDocumentation
+ *
+ * Role-based data access control (DAC) helpers that compare resource paths
+ * against role constraints. Constraints can be exact matches or prefixes, and
+ * can include wildcard signifiers for flexible path matching.
+ *
+ * Example role policy:
+ * ```ts
+ * import {
+ *   DACConstraintType,
+ *   DACRole,
+ *   getResourceAccessByDACRole,
+ *   WILDCARD_SIGNIFIER_PROTOTYPE,
+ * } from "./DataAccessControl";
+ *
+ * const wildcard = WILDCARD_SIGNIFIER_PROTOTYPE;
+ * const readerRole: DACRole = {
+ *   id: "reader",
+ *   constraints: [
+ *     {
+ *       type: DACConstraintType.ALLOW,
+ *       resourcePath: ["books", wildcard],
+ *       pathIsPrefix: true,
+ *     },
+ *     {
+ *       type: DACConstraintType.DENY,
+ *       resourcePath: ["books", "restricted"],
+ *       pathIsPrefix: true,
+ *     },
+ *   ],
+ * };
+ *
+ * const getDACRoleById = async (id: string) =>
+ *   id === readerRole.id ? readerRole : readerRole;
+ *
+ * const access = await getResourceAccessByDACRole(
+ *   ["books", "public"],
+ *   readerRole,
+ *   getDACRoleById,
+ * );
+ * ```
+ */
+import { LiteralValue } from "../common/TypeParsing/TypeInfo";
+/**
+ * The possible types of a data access control (DAC) constraint.
+ * */
+export declare enum DACConstraintType {
+    ALLOW = "ALLOW",
+    DENY = "DENY"
+}
+/**
+ * A wildcard segment used in DAC resource paths.
+ * */
+export type DACWildcardSignifier = {
+    WILD_CARD: "*";
+};
+/**
+ * A data access control (DAC) constraint.
+ * */
+export type DACResourcePathPart = LiteralValue | DACWildcardSignifier;
+/**
+ * An ordered list of resource path segments used in DAC constraints.
+ */
+export type DACResourcePath = DACResourcePathPart[];
+/**
+ * A data access control (DAC) constraint that defines an allow or deny rule for a resource path.
+ */
+export type DACConstraint = {
+    /**
+     * Whether the constraint explicitly allows or denies access.
+     */
+    type: DACConstraintType;
+    /**
+     * The resource path to match against, in order of path segments.
+     */
+    resourcePath: DACResourcePath;
+    /**
+     * When true, match the resource path as a prefix instead of an exact match.
+     */
+    pathIsPrefix?: boolean;
+};
+/**
+ * The primary properties for a data access control (DAC) role.
+ * */
+export type BaseDACRole = {
+    /**
+     * Child role ids whose constraints are included in this role.
+     */
+    childRoleIds?: string[];
+    /**
+     * Constraints directly assigned to this role.
+     */
+    constraints: DACConstraint[];
+};
+/**
+ * A data access control (DAC) role which has been stored and can be accessed by an `id`.
+ * */
+export type DACRole = {
+    /**
+     * Stable role identifier used for lookups and inheritance.
+     */
+    id: string;
+} & BaseDACRole;
+/**
+ * The result of a data access control (DAC) check.
+ * */
+export type DACAccessResult = {
+    /**
+     * True if any matching rule allows access.
+     */
+    allowed: boolean;
+    /**
+     * True if any matching rule denies access.
+     */
+    denied: boolean;
+};
+/**
+ * The result of a data access control (DAC) check for a data item.
+ * */
+export type DACDataItemResourceAccessResultMap = DACAccessResult & {
+    /**
+     * Per-field access results, keyed by field name.
+     */
+    fieldsResources?: Record<string, DACAccessResult>;
+};
+/**
+ * The result of matching a DAC path to a resource path.
+ * */
+export type DACPathMatchResults = {
+    /**
+     * True when the DAC path is a prefix of the resource path.
+     */
+    prefixMatch: boolean;
+    /**
+     * True when the DAC path matches the resource path exactly.
+     */
+    exactMatch: boolean;
+};
+/**
+ * The prototype of a DAC wildcard signifier.
+ * */
+export declare const WILDCARD_SIGNIFIER_PROTOTYPE: DACWildcardSignifier;
+/**
+ * Check if a given DAC path part value is a DAC wildcard signifier.
+ * @returns True when the value matches the wildcard signifier prototype.
+ * */
+export declare const getValueIsWildcardSignifier: (
+/**
+ * Value to test against the wildcard signifier prototype.
+ */
+value: any) => boolean;
+/**
+ * Check if a given DAC path matches a given resource path.
+ *
+ * Includes checking if the DAC path is a prefix of the
+ * resource path and if the DAC path is an exact match of
+ * the resource path.
+ *
+ * The DAC path can include wildcard signifier objects at
+ * various indices in order to facilitate dynamic matches
+ * and grouping by common resource aspects.
+ * @returns Prefix and exact match flags for the comparison.
+ * */
+export declare const getDACPathsMatch: (
+/**
+ * DAC constraint path to evaluate for prefix/exact matches.
+ */
+dacPath: DACResourcePath, 
+/**
+ * Resource path to compare against the DAC path.
+ */
+resourcePath: LiteralValue[]) => DACPathMatchResults;
+/**
+ * Get the flattened constraints of a DAC role.
+ * @returns Flattened constraint list including child roles.
+ * */
+export declare const getFlattenedDACConstraints: (
+/**
+ * Role whose constraints (and child role constraints) are flattened.
+ */
+role: DACRole, 
+/**
+ * Lookup helper used to resolve child roles by id.
+ */
+getDACRoleById: (id: string) => Promise<DACRole>, 
+/**
+ * SECURITY: Don't use this if you want realtime role resolution.
+ * */
+dacRoleCache?: Record<string, DACRole>) => Promise<DACConstraint[]>;
+/**
+ * Get the access to a given resource for a given DAC role.
+ * @returns Allow/deny summary for the resource path.
+ * */
+export declare const getResourceAccessByDACRole: (
+/**
+ * Full resource path to test against the role's constraints.
+ */
+fullResourcePath: LiteralValue[], 
+/**
+ * Role to evaluate for access on the given resource path.
+ */
+role: DACRole, 
+/**
+ * Lookup helper used to resolve child roles by id.
+ */
+getDACRoleById: (id: string) => Promise<DACRole>, 
+/**
+ * Optional cache to reuse resolved roles across calls.
+ */
+dacRoleCache?: Record<string, DACRole>) => Promise<DACAccessResult>;
+/**
+ * Merge multiple DAC access results.
+ * @returns Combined allow/deny result.
+ * */
+export declare const mergeDACAccessResults: (
+/**
+ * Access results to merge into a single allow/deny summary.
+ */
+...results: DACAccessResult[]) => DACAccessResult;

package/api/Indexing/API.d.ts

@@ -0,0 +1,224 @@
+import type { DocId, DocumentRecord, IndexBackend } from "./Types";
+import { type ResolvedSearchLimits } from "./Handler/Config";
+import type { SearchTrace } from "./Trace";
+/**
+ * Input for indexing a document.
+ * */
+export type IndexDocumentInput = {
+    /**
+     * Document record to index.
+     */
+    document: DocumentRecord;
+    /**
+     * Field name used as the document id.
+     */
+    primaryField: string;
+    /**
+     * Field name containing the text to index.
+     */
+    indexField: string;
+    /**
+     * Optional index field key to use for persistence when the index key should
+     * be type-qualified. Defaults to indexField.
+     */
+    indexFieldQualified?: string;
+    /**
+     * Optional backend override (defaults to configured backend).
+     */
+    backend?: IndexBackend;
+};
+/**
+ * Input for removing a document from the index.
+ * */
+export type RemoveDocumentInput = {
+    /**
+     * Document record to remove.
+     */
+    document: DocumentRecord;
+    /**
+     * Field name used as the document id.
+     */
+    primaryField: string;
+    /**
+     * Field name containing the text to remove from the index.
+     */
+    indexField: string;
+    /**
+     * Optional index field key to use for persistence when the index key should
+     * be type-qualified. Defaults to indexField.
+     */
+    indexFieldQualified?: string;
+    /**
+     * Optional backend override (defaults to configured backend).
+     */
+    backend?: IndexBackend;
+};
+/**
+ * Input for replacing a document in the index.
+ * */
+export type ReplaceDocumentInput = {
+    /**
+     * Previous document record to remove.
+     */
+    previousDocument: DocumentRecord;
+    /**
+     * Next document record to index.
+     */
+    nextDocument: DocumentRecord;
+    /**
+     * Field name used as the document id.
+     */
+    primaryField: string;
+    /**
+     * Field name containing the text to index.
+     */
+    indexField: string;
+    /**
+     * Optional index field key to use for persistence when the index key should
+     * be type-qualified. Defaults to indexField.
+     */
+    indexFieldQualified?: string;
+    /**
+     * Optional backend override (defaults to configured backend).
+     */
+    backend?: IndexBackend;
+};
+/**
+ * Input for lossy search with paging support.
+ * */
+export type SearchLossyInput = {
+    /**
+     * Search query string.
+     */
+    query: string;
+    /**
+     * Field name containing the indexed text.
+     */
+    indexField: string;
+    /**
+     * Optional maximum number of results to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+    /**
+     * Optional backend override (defaults to configured backend).
+     */
+    backend?: IndexBackend;
+    /**
+     * Optional limits override for search execution.
+     */
+    limits?: ResolvedSearchLimits;
+    /**
+     * Optional trace instance for metrics collection.
+     */
+    trace?: SearchTrace;
+};
+/**
+ * Input for exact search with verification/paging support.
+ * */
+export type SearchExactInput = {
+    /**
+     * Search query string.
+     */
+    query: string;
+    /**
+     * Field name containing the indexed text.
+     */
+    indexField: string;
+    /**
+     * Optional maximum number of results to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+    /**
+     * Optional backend override (defaults to configured backend).
+     */
+    backend?: IndexBackend;
+    /**
+     * Optional limits override for search execution.
+     */
+    limits?: ResolvedSearchLimits;
+    /**
+     * Optional trace instance for metrics collection.
+     */
+    trace?: SearchTrace;
+};
+/**
+ * Search results with normalized tokens and an optional cursor.
+ * */
+export type SearchResult = {
+    /**
+     * Normalized query string.
+     */
+    normalized: string;
+    /**
+     * Tokens derived from the normalized query.
+     */
+    tokens: string[];
+    /**
+     * Matching document ids.
+     */
+    docIds: DocId[];
+    /**
+     * Cursor string for the next page, if more results exist.
+     */
+    nextCursor?: string;
+};
+/**
+ * Set the default backend used by search and mutation calls.
+ * @param backend Backend to use for subsequent operations.
+ * @returns Nothing.
+ * */
+export declare function setIndexBackend(
+/**
+ * Backend to use for subsequent indexing and search operations.
+ */
+backend: IndexBackend): void;
+/**
+ * Index a document using exact and lossy backends.
+ *
+ * Accepts {@link IndexDocumentInput} with document data, field configuration,
+ * and an optional backend override.
+ * @returns Promise resolved once indexing is complete.
+ * */
+export declare function indexDocument({ document, primaryField, indexField, indexFieldQualified, backend, }: IndexDocumentInput): Promise<void>;
+/**
+ * Remove a document from exact and lossy backends.
+ *
+ * Accepts {@link RemoveDocumentInput} with document data, field configuration,
+ * and an optional backend override.
+ * @returns Promise resolved once removal is complete.
+ * */
+export declare function removeDocument({ document, primaryField, indexField, indexFieldQualified, backend, }: RemoveDocumentInput): Promise<void>;
+/**
+ * Replace a document in exact and lossy backends.
+ *
+ * Accepts {@link ReplaceDocumentInput} with previous/next documents, field
+ * configuration, and an optional backend override.
+ * @returns Promise resolved once replacement is complete.
+ * @remarks Replacement is remove-then-add; a failure between steps can
+ * temporarily hide the document until retried.
+ * */
+export declare function replaceFullTextDocument({ previousDocument, nextDocument, primaryField, indexField, indexFieldQualified, backend, }: ReplaceDocumentInput): Promise<void>;
+/**
+ * Perform a lossy search and return matching document ids.
+ *
+ * Accepts {@link SearchLossyInput} with query text, paging/limit options,
+ * optional execution limits, and an optional trace collector.
+ * @returns Search results with doc ids and optional next cursor.
+ * */
+export declare function searchLossy({ query, indexField, limit, cursor, backend, limits, trace, }: SearchLossyInput): Promise<SearchResult>;
+/**
+ * Perform an exact search, optionally using a lossy pre-pass for candidates.
+ *
+ * Accepts {@link SearchExactInput} with query text, paging/limit options,
+ * optional execution limits, and an optional trace collector.
+ * @returns Search results with doc ids and optional next cursor.
+ * */
+export declare function searchExact({ query, indexField, limit, cursor, backend, limits, trace, }: SearchExactInput): Promise<SearchResult>;