@resistdesign/voltra 3.0.0-alpha.14 → 3.0.0-alpha.16

package/README.md

@@ -24,9 +24,8 @@ cross-runtime bundling issues.
 Preferred:
 
 ```ts
-import * as IaC from "@resistdesign/voltra/iac";
-import {Packs} from "@resistdesign/voltra/iac";
-import {addDNS} from "@resistdesign/voltra/iac/packs";
+import { SimpleCFT, Packs } from "@resistdesign/voltra/iac";
+import { addDNS } from "@resistdesign/voltra/iac/packs";
 ```
 
 Not supported:
@@ -46,6 +45,19 @@ Public entrypoints:
 - `@resistdesign/voltra/iac/packs`
 - `@resistdesign/voltra/build`
 
+Common imports by domain:
+
+```ts
+import { addRoutesToRouteMap, handleCloudFunctionEvent } from "@resistdesign/voltra/api";
+import { TypeInfo, TypeInfoORMServiceError } from "@resistdesign/voltra/common";
+import { parseTemplate, computeTrackPixels } from "@resistdesign/voltra/app";
+import { AutoField, AutoForm, createWebFormRenderer, getEasyLayout } from "@resistdesign/voltra/web";
+import { createNativeFormRenderer, makeNativeEasyLayout } from "@resistdesign/voltra/native";
+import { SimpleCFT, Packs } from "@resistdesign/voltra/iac";
+import { addDNS } from "@resistdesign/voltra/iac/packs";
+import { getTypeInfoMapFromTypeScript } from "@resistdesign/voltra/build";
+```
+
 ------------
 
 ## Build-time Type Parsing (Advanced)
@@ -103,10 +115,18 @@ App features include form generation via TypeInfo-driven AutoForm/AutoField with
 
 EasyLayout now has:
 
-- Shared core parsing/math in `@resistdesign/voltra/app` (`Utils.parseTemplate`, `Utils.computeTrackPixels`, etc.).
+- Shared core parsing/math in `@resistdesign/voltra/app` (`parseTemplate`, `computeTrackPixels`, etc.).
 - Web rendering via CSS Grid in `@resistdesign/voltra/web`.
 - Native coordinate computation in `@resistdesign/voltra/native`.
 
+### Examples
+
+- `examples/api.ts`
+- `examples/common.ts`
+- `examples/web.ts`
+- `examples/native.ts`
+- `examples/build.ts`
+
 ### Template syntax
 
 ```text
@@ -123,9 +143,9 @@ side main, 2fr
 ### Web usage
 
 ```tsx
-import { Utils as WebUtils } from "@resistdesign/voltra/web";
+import { getEasyLayout } from "@resistdesign/voltra/web";
 
-const { layout: Layout, areas } = WebUtils.getEasyLayout(undefined, undefined, {
+const { layout: Layout, areas } = getEasyLayout(undefined, undefined, {
   gap: 12,
   padding: 16,
 })`
@@ -138,9 +158,9 @@ const { layout: Layout, areas } = WebUtils.getEasyLayout(undefined, undefined, {
 ### Native usage
 
 ```tsx
-import { Utils as NativeUtils } from "@resistdesign/voltra/native";
+import { makeNativeEasyLayout } from "@resistdesign/voltra/native";
 
-const layout = NativeUtils.makeNativeEasyLayout(`
+const layout = makeNativeEasyLayout(`
   header header, 100px
   side main, 1fr
   \\ 1fr 2fr
@@ -168,17 +188,13 @@ Voltra ships a render-agnostic Route core in `@resistdesign/voltra/app` plus pla
 Web usage (auto-wires `window.history`):
 
 ```tsx
-import { Utils as WebUtils } from "@resistdesign/voltra/web";
-
-const { Route } = WebUtils;
+import { Route } from "@resistdesign/voltra/web";
 ```
 
 Native usage (adapter-driven):
 
 ```tsx
-import { Utils as NativeUtils } from "@resistdesign/voltra/native";
-
-const { Route, RouteProvider, createManualRouteAdapter } = NativeUtils;
+import { Route, RouteProvider, createManualRouteAdapter } from "@resistdesign/voltra/native";
 const { adapter, updatePath } = createManualRouteAdapter("/home");
 ```
 
@@ -187,9 +203,7 @@ For React Native navigation libraries, Voltra is optimized for react-navigation
 Native navigation mapping example:
 
 ```tsx
-import { Utils as NativeUtils } from "@resistdesign/voltra/native";
-
-const { createNavigationStateRouteAdapter, buildPathFromRouteChain } = NativeUtils;
+import { buildPathFromRouteChain, createNavigationStateRouteAdapter } from "@resistdesign/voltra/native";
 
 const adapter = createNavigationStateRouteAdapter({
   getState: () => navigationRef.getRootState(),
@@ -225,18 +239,19 @@ Voltra's form system is split into a platform-agnostic core and platform suites:
 ### Web Usage
 
 ```tsx
-import { Forms } from "@resistdesign/voltra/web";
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
 
-const { AutoField } = Forms.createWebFormRenderer();
+const { AutoField } = createWebFormRenderer();
 ```
 
 Override a single renderer:
 
 ```tsx
-import { Forms } from "@resistdesign/voltra/web";
+import { withRendererOverride } from "@resistdesign/voltra/app";
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
 
-const { AutoField } = Forms.createWebFormRenderer({
-  suite: Forms.withRendererOverride("string", (ctx) => {
+const { AutoField } = createWebFormRenderer({
+  suite: withRendererOverride("string", (ctx) => {
     return <input value={(ctx.value as string) || ""} onChange={(e) => ctx.onChange(e.target.value)} />;
   }),
 });
@@ -245,9 +260,9 @@ const { AutoField } = Forms.createWebFormRenderer({
 ### Native Usage
 
 ```tsx
-import { Forms } from "@resistdesign/voltra/native";
+import { createNativeFormRenderer } from "@resistdesign/voltra/native";
 
-const { AutoField } = Forms.createNativeFormRenderer();
+const { AutoField } = createNativeFormRenderer();
 ```
 
 ### BYOCS (Bring Your Own Component Suite)
@@ -255,9 +270,9 @@ const { AutoField } = Forms.createNativeFormRenderer();
 Provide partial overrides (renderers and/or primitives). Missing renderers are filled from the default suite and validated.
 
 ```tsx
-import { Forms } from "@resistdesign/voltra/web";
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
 
-const { AutoField } = Forms.createWebFormRenderer({
+const { AutoField } = createWebFormRenderer({
   suite: {
     primitives: {
       Button: ({ children }) => <button className="my-button">{children}</button>,

package/api/DBX/DBXAsserts.d.ts

@@ -0,0 +1,95 @@
+import type { ListItemsResults } from "../../common/SearchTypes";
+/**
+ * Summary of IDs and cursors observed across pages.
+ */
+export type DBXPagingTranscript = {
+    /**
+     * Number of pages inspected.
+     */
+    pageCount: number;
+    /**
+     * Cursors observed per page.
+     */
+    cursors: Array<string | undefined>;
+    /**
+     * IDs grouped by page.
+     */
+    idsByPage: string[][];
+    /**
+     * Flattened IDs across all pages (page order preserved).
+     */
+    flattenedIds: string[];
+};
+/**
+ * Results from paging invariant checks.
+ */
+export type DBXPagingAssertionResult = {
+    /**
+     * True when no invariant violations were detected.
+     */
+    ok: boolean;
+    /**
+     * Total items observed across all pages.
+     */
+    totalItems: number;
+    /**
+     * Number of unique IDs observed across all pages.
+     */
+    uniqueItems: number;
+    /**
+     * IDs that appeared more than once.
+     */
+    duplicateIds: string[];
+    /**
+     * Pages with zero items.
+     */
+    emptyPageIndexes: number[];
+    /**
+     * Pages that violated the expected page size.
+     */
+    pageSizeViolations: Array<{
+        index: number;
+        size: number;
+    }>;
+    /**
+     * Raw paging transcript for debugging.
+     */
+    transcript: DBXPagingTranscript;
+};
+/**
+ * Results from ordering checks against an expected sequence.
+ */
+export type DBXOrderingAssertionResult = {
+    /**
+     * True when actual ordering matches expected ordering.
+     */
+    ok: boolean;
+    /**
+     * Actual IDs in observed order.
+     */
+    actualIds: string[];
+    /**
+     * Expected IDs for comparison.
+     */
+    expectedIds: string[];
+    /**
+     * First mismatched index, if any.
+     */
+    mismatchIndex?: number;
+};
+/**
+ * Build a paging transcript for a set of list results.
+ */
+export declare const getDbxPagingTranscript: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, idField?: string) => DBXPagingTranscript;
+/**
+ * Assert paging invariants such as stable pagination and no duplicates.
+ */
+export declare const assertDbxPagingInvariants: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, options?: {
+    idField?: string;
+    itemsPerPage?: number;
+    allowEmptyPages?: boolean;
+}) => DBXPagingAssertionResult;
+/**
+ * Assert that the observed ordering exactly matches an expected ordering.
+ */
+export declare const assertDbxStableOrdering: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, expectedIds: string[], idField?: string) => DBXOrderingAssertionResult;

package/api/DBX/DBXRequest.d.ts

@@ -0,0 +1,5 @@
+import type { DBXRequestInput, DBXResponse, DBXRuntime } from "./DBXTypes";
+/**
+ * Run a DBX request through the router.
+ */
+export declare const runDbxRequest: <T = unknown>(runtime: DBXRuntime, request: DBXRequestInput) => Promise<DBXResponse<T>>;

package/api/DBX/DBXRuntime.d.ts

@@ -0,0 +1,5 @@
+import type { DBXRuntime, DBXRuntimeConfig } from "./DBXTypes";
+/**
+ * Build an in-memory runtime for DBX scenarios.
+ */
+export declare const createDbxRuntime: (config: DBXRuntimeConfig) => DBXRuntime;

package/api/DBX/DBXScenarioConfig.d.ts

@@ -0,0 +1,9 @@
+import type { TypeInfoMap } from "../../common/TypeParsing/TypeInfo";
+/**
+ * Canonical TypeInfo map used by DBX E2E scenario tests.
+ */
+export declare const DBX_TYPE_INFO_MAP: TypeInfoMap;
+/**
+ * Ordered list of DBX scenario type names.
+ */
+export declare const DBX_TYPE_NAMES: string[];

package/api/DBX/DBXSeed.d.ts

@@ -0,0 +1,124 @@
+import type { TypeInfoDataItem, TypeInfoMap } from "../../common/TypeParsing/TypeInfo";
+/**
+ * Dataset size presets for DBX scenarios.
+ */
+export declare const DBX_DATASET_SIZES: {
+    readonly SMALL: 50;
+    readonly MED: 200;
+    readonly LARGE: 1000;
+};
+/**
+ * Relationship edge shape used by DBX seeds.
+ */
+export type DBXSeedRelationship = {
+    /**
+     * Type name of the relationship origin.
+     */
+    fromTypeName: string;
+    /**
+     * Field name on the origin type that defines the relationship.
+     */
+    fromTypeFieldName: string;
+    /**
+     * Primary field value for the origin item.
+     */
+    fromTypePrimaryFieldValue: string;
+    /**
+     * Primary field value for the target item.
+     */
+    toTypePrimaryFieldValue: string;
+};
+/**
+ * Configuration for generating a DBX dataset.
+ */
+export type DBXSeedConfig = {
+    /**
+     * Seed used for deterministic generation.
+     */
+    seed: number | string;
+    /**
+     * Type info map used to shape items.
+     */
+    typeInfoMap: TypeInfoMap;
+    /**
+     * Optional list of type names to seed.
+     */
+    itemTypeNames?: string[];
+    /**
+     * Default item count per type when sizeByType is not provided.
+     */
+    size?: number;
+    /**
+     * Optional per-type overrides for item counts.
+     */
+    sizeByType?: Record<string, number>;
+    /**
+     * Optional base date for date-like string fields.
+     */
+    baseDate?: string;
+    /**
+     * Whether to include optional fields (default true).
+     */
+    includeOptionalFields?: boolean;
+    /**
+     * Whether to include array fields (default true).
+     */
+    includeArrayFields?: boolean;
+    /**
+     * Max array length when generating array fields.
+     */
+    maxArrayLength?: number;
+    /**
+     * Custom token pool for text generation.
+     */
+    textTokenPool?: string[];
+    /**
+     * Whether to include relationship edges (default true).
+     */
+    includeRelationships?: boolean;
+    /**
+     * Ratio of relationship edges that should point at missing targets.
+     */
+    relationshipDanglingRate?: number;
+    /**
+     * Number of relationships to generate per item when possible.
+     */
+    relationshipsPerItem?: number;
+};
+/**
+ * Seeded dataset payload returned by {@link makeDbxDataset}.
+ */
+export type DBXSeedDataset = {
+    /**
+     * Seed used for deterministic generation.
+     */
+    seed: number | string;
+    /**
+     * Items keyed by type name.
+     */
+    itemsByType: Record<string, TypeInfoDataItem[]>;
+    /**
+     * Generated ids per type name.
+     */
+    idsByType: Record<string, string[]>;
+    /**
+     * Relationship edges seeded for scenarios.
+     */
+    relationships: DBXSeedRelationship[];
+    /**
+     * Token pool used for text values.
+     */
+    tokenPool: string[];
+};
+/**
+ * Generate a deterministic dataset for DBX scenarios.
+ */
+export declare const makeDbxDataset: (config: DBXSeedConfig) => DBXSeedDataset;
+/**
+ * Build relationship seeds from existing items.
+ */
+export declare const makeDbxRelationshipSeeds: (typeInfoMap: TypeInfoMap, itemsByType: Record<string, TypeInfoDataItem[]>, idsByType: Record<string, string[]>, options: {
+    seed: number | string;
+    relationshipDanglingRate?: number;
+    relationshipsPerItem?: number;
+}) => DBXSeedRelationship[];

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";