@workglow/test-contract 0.6.1

package/dist/tabular-storage/joinFixtures.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITabularStorage } from "@workglow/storage";
+import type { FromSchema } from "@workglow/util/schema";
+export declare const AuthorPrimaryKeyNames: readonly ["id"];
+export declare const AuthorSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly tenant: {
+            readonly type: "string";
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly country: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
+    readonly required: readonly ["id", "tenant", "name", "country"];
+    readonly additionalProperties: false;
+};
+export declare const PostPrimaryKeyNames: readonly ["id"];
+export declare const PostSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly tenant: {
+            readonly type: "string";
+        };
+        readonly author_id: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly views: {
+            readonly type: "number";
+        };
+    };
+    readonly required: readonly ["id", "tenant", "author_id", "title", "views"];
+    readonly additionalProperties: false;
+};
+export type AuthorStorage = ITabularStorage<typeof AuthorSchema, typeof AuthorPrimaryKeyNames>;
+export type PostStorage = ITabularStorage<typeof PostSchema, typeof PostPrimaryKeyNames>;
+export type JoinFixtureAuthor = FromSchema<typeof AuthorSchema>;
+export type JoinFixturePost = FromSchema<typeof PostSchema>;
+export declare const JOIN_FIXTURE_AUTHORS: JoinFixtureAuthor[];
+export declare const JOIN_FIXTURE_POSTS: JoinFixturePost[];
+/** Loads both fixture tables, right side first so a left read never races it. */
+export declare function seedJoinFixtures(posts: ITabularStorage<typeof PostSchema, typeof PostPrimaryKeyNames>, authors: ITabularStorage<typeof AuthorSchema, typeof AuthorPrimaryKeyNames>): Promise<void>;

package/dist/tabular-storage/runTabularJoinContract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AuthorStorage, PostStorage } from "./joinFixtures";
+export { AuthorPrimaryKeyNames, AuthorSchema, JOIN_FIXTURE_AUTHORS, JOIN_FIXTURE_POSTS, PostPrimaryKeyNames, PostSchema, seedJoinFixtures, } from "./joinFixtures";
+export type { AuthorStorage, JoinFixtureAuthor, JoinFixturePost, PostStorage, } from "./joinFixtures";
+export interface JoinTestOptions {
+    /**
+     * Which path the pair is expected to take. The proof is backend-agnostic:
+     * the right storage's `query` is never called on the pushed-down path
+     * (`true`) and always called on the hash-join path (`false`). Leave it unset
+     * for a wrapper pair — a wrapper hands its inner storage to the join, so
+     * the call lands on the inner's `query`, not the wrapper's.
+     */
+    readonly expectSqlPushdown?: boolean;
+    readonly timeout?: number;
+}
+/**
+ * Shared join behaviour, run per backend pair. `createPosts` is the left
+ * side; `createAuthors` the right. Both are created fresh for every test.
+ */
+export declare function runTabularJoinContract(createPosts: () => Promise<PostStorage>, createAuthors: () => Promise<AuthorStorage>, opts?: JoinTestOptions): void;

package/dist/tabular-storage/runTabularStorageContract.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "./types";
+export declare function runTabularStorageContract(opts: TabularStorageContractOpts): void;
+export { VectorItemPrimaryKeyNames, VectorItemSchema } from "./types";
+export type { TabularStorageContractAssertion, TabularStorageContractOpts } from "./types";

package/dist/tabular-storage/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITabularStorage } from "@workglow/storage";
+import type { CompoundPrimaryKeyNames, CompoundSchema } from "./fixtures";
+export declare const VectorItemPrimaryKeyNames: readonly ["id"];
+export declare const VectorItemSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly embedding: {
+            readonly type: "array";
+            readonly format: "TypedArray:Float32Array";
+        };
+    };
+    readonly required: readonly ["id", "embedding"];
+    readonly additionalProperties: false;
+};
+/**
+ * Closed string-literal union of tabular-storage contract assertions that
+ * adapters can mark as known failing. A typo in `expectedFailures` becomes
+ * a TS error rather than a silently-ignored entry.
+ */
+export type TabularStorageContractAssertion = "subscribeToChanges" | "vectorColumnFormat" | "withTransactionRollback" | "withConnectionTransaction" | "countMatchesQuery" | "inListCriterion" | "notInListCriterion" | "joinPushdown" | "guardParity";
+interface TabularStorageContractBaseOpts {
+    readonly name: string;
+    readonly skip?: boolean;
+    readonly timeout?: number;
+    readonly createStorage: () => Promise<ITabularStorage<typeof CompoundSchema, typeof CompoundPrimaryKeyNames>>;
+    /**
+     * Required when capabilities.supportsVectorColumns is true. Creates a fresh
+     * storage instance typed to VectorItemSchema for the round-trip assertion.
+     */
+    readonly createVectorStorage?: () => Promise<ITabularStorage<typeof VectorItemSchema, typeof VectorItemPrimaryKeyNames>>;
+    /**
+     * Creates a second table on the same connection handle as `primary`.
+     * Required for the `withConnectionTransaction` assertion; backends that
+     * cannot share a handle (InMemory, FsFolder, IndexedDB, Supabase) omit it
+     * and that block is skipped.
+     */
+    readonly createSiblingStorage?: (primary: ITabularStorage<typeof CompoundSchema, typeof CompoundPrimaryKeyNames>) => Promise<ITabularStorage<typeof CompoundSchema, typeof CompoundPrimaryKeyNames>>;
+    /**
+     * Releases whatever a factory allocated that the storage itself does not
+     * own — typically a connection handle the adapter opened so `createStorage`
+     * and `createSiblingStorage` could share one. Called from every `afterEach`
+     * after `destroy()`, and passed the same instance the factory returned.
+     *
+     * Without it an adapter that opens its own handle has nowhere to close it:
+     * `destroy()` deliberately leaves a caller-provided handle open, so the
+     * handles pile up until the file ends. The parameter is `object` because
+     * the hook is identity-keyed — the contract creates storages of two
+     * different schema types and a release hook only ever looks its argument up.
+     */
+    readonly releaseStorage?: (storage: object) => void | Promise<void>;
+    /**
+     * Names of contract assertions currently broken in this adapter; each
+     * named test wraps with `itExpectFail`. The string-literal union catches
+     * typos at compile time.
+     */
+    readonly expectedFailures?: ReadonlyArray<TabularStorageContractAssertion>;
+}
+interface SubscriptionCapableCapabilities {
+    readonly supportsSubscriptions: true;
+    readonly supportsVectorColumns: boolean;
+    readonly supportsTransactions: boolean;
+    /** Whether `query(criteria)` is supported. False for FsFolder etc. */
+    readonly supportsQuery: boolean;
+}
+interface SubscriptionCapableOpts extends TabularStorageContractBaseOpts {
+    readonly capabilities: SubscriptionCapableCapabilities;
+    /**
+     * Required when supportsSubscriptions is true. Selects between the two
+     * subscribeToChanges contract blocks:
+     *   - false → eventDriven (strict commit order)
+     *   - true  → polling (set equality + count)
+     */
+    readonly usesPolling: boolean;
+    /** Polling interval forwarded to subscribeToChanges for polling-based implementations. */
+    readonly pollingIntervalMs?: number;
+}
+interface SubscriptionIncapableCapabilities {
+    readonly supportsSubscriptions: false;
+    readonly supportsVectorColumns: boolean;
+    readonly supportsTransactions: boolean;
+    /** Whether `query(criteria)` is supported. False for FsFolder etc. */
+    readonly supportsQuery: boolean;
+}
+interface SubscriptionIncapableOpts extends TabularStorageContractBaseOpts {
+    readonly capabilities: SubscriptionIncapableCapabilities;
+    /**
+     * Only meaningful when supportsSubscriptions is true. Permitted (but
+     * ignored) on incapable backends to keep wiring ergonomic.
+     */
+    readonly usesPolling?: boolean;
+    readonly pollingIntervalMs?: number;
+}
+export type TabularStorageContractOpts = SubscriptionCapableOpts | SubscriptionIncapableOpts;
+export {};

package/dist/tabular-storage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Conformance suite for `ITabularStorage` — the behaviour every backend owes a
+ * caller, including the two join strategies and the guards that bound them.
+ */
+export * from "./tabular-storage/assertions/countMatchesQuery";
+export * from "./tabular-storage/assertions/guardParity";
+export * from "./tabular-storage/assertions/inListCriterion";
+export * from "./tabular-storage/assertions/joinBoundedLeftRead";
+export * from "./tabular-storage/assertions/joinPushdown";
+export * from "./tabular-storage/assertions/notInListCriterion";
+export * from "./tabular-storage/assertions/strategyParity";
+export * from "./tabular-storage/assertions/subscribeToChanges";
+export * from "./tabular-storage/assertions/vectorColumnFormat";
+export * from "./tabular-storage/assertions/withConnectionTransaction";
+export * from "./tabular-storage/assertions/withTransactionRollback";
+export * from "./tabular-storage/fixtures";
+export * from "./tabular-storage/joinFixtures";
+export * from "./tabular-storage/runTabularJoinContract";
+export * from "./tabular-storage/runTabularStorageContract";
+export * from "./tabular-storage/types";