@nxgt/janus 0.1.0

package/dist/conformance/describe.d.ts

@@ -0,0 +1,74 @@
+import type { ConformanceCase, ConformanceHarness, ConformanceRunner } from './types';
+/** Every case, in the order they are described. */
+export declare const allCases: readonly ConformanceCase[];
+/** Why a case did not run. A skip is always reported with its reason, never silent. */
+export declare const SKIP_REASONS: {
+    readonly faults: "faults not provided: the outage invariant is not proven for this adapter";
+    readonly deleteExpiredSessions: "stores.sessions does not implement the optional deleteExpiredSessions";
+};
+/**
+ * Runs one case against one freshly opened set of stores, and closes them,
+ * pass or fail. Answers the reason when the case cannot run on these stores.
+ *
+ * The runner-less layer: a loop over `allCases` calling this is a conformance
+ * run with no test framework at all.
+ */
+export declare function runCase(conformanceCase: ConformanceCase, harness: ConformanceHarness): Promise<{
+    readonly skipped: string;
+} | {
+    readonly passed: true;
+}>;
+/**
+ * Describes the whole suite under the adapter's test runner.
+ *
+ * ```ts
+ * import { describe, it } from 'bun:test';
+ * describeJanusStores({ name: 'my adapter', harness, runner: { describe, it } });
+ * ```
+ *
+ * `runner` may be left out under jest, or vitest with `globals: true`: the
+ * suite then reads `describe` and `it` from `globalThis`. **Not under `bun
+ * test`**, measured: Bun gives a test file `describe` and `it` as bare
+ * identifiers, and not as properties of `globalThis` — so pass them.
+ *
+ * Whether a case can run depends on the stores its harness opens, which is only
+ * known once they are open. So every case is described as a test; one that
+ * cannot run passes **and says so in its name**, and a run without `faults`
+ * is written above the suite, where it cannot be scrolled past.
+ */
+export declare function describeJanusStores(options: {
+    readonly name: string;
+    readonly harness: ConformanceHarness;
+    readonly runner?: ConformanceRunner;
+    /** Case ids to skip, each with the reason — reported, never silent. */
+    readonly skip?: Readonly<Record<string, string>>;
+    /** Declared up front, so the report can say so before the first case runs. */
+    readonly faults?: boolean;
+}): void;
+/** What any suite's case declares, as far as describing it goes. */
+interface DescribedCase {
+    readonly id: string;
+    readonly group: string;
+    readonly name: string;
+    readonly needs?: string;
+}
+/**
+ * Describes one suite's cases, grouped, under a runner. Shared by every suite
+ * this module exports, so a skip, an unproven outage and a missing runner read
+ * the same in each.
+ */
+export declare function describeSuite<C extends DescribedCase>(options: {
+    readonly title: string;
+    readonly cases: readonly C[];
+    readonly run: (conformanceCase: C) => Promise<{
+        readonly skipped: string;
+    } | {
+        readonly passed: true;
+    }>;
+    readonly runner: ConformanceRunner;
+    readonly skip: Readonly<Record<string, string>>;
+    readonly faults: boolean | undefined;
+}): void;
+export declare function fromGlobals(where: string): ConformanceRunner;
+export {};
+//# sourceMappingURL=describe.d.ts.map

package/dist/conformance/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/conformance/describe.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EAEjB,MAAM,SAAS,CAAC;AAEjB,mDAAmD;AACnD,eAAO,MAAM,QAAQ,EAAE,SAAS,eAAe,EAK9C,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,YAAY;;;CAKf,CAAC;AAEX;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC5B,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC,CAsBnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,IAAI,CASP;AAED,oEAAoE;AACpE,UAAU,aAAa;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,aAAa,EAAE,OAAO,EAAE;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,CACb,eAAe,EAAE,CAAC,KACd,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACvE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC,GAAG,IAAI,CA0CP;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAgB5D"}

package/dist/conformance/fixtures.d.ts

@@ -0,0 +1,11 @@
+import type { SessionRecord, TokenRecord, UserRecord } from '../auth/port/types';
+/**
+ * Records the cases write. Every id is minted, so no two cases — and no two
+ * records of one case — ever collide by accident; every collision a case
+ * tests is one it wrote on purpose.
+ */
+export declare const at: (iso: string) => Date;
+export declare function userRecord(overrides?: Partial<UserRecord>): UserRecord;
+export declare function sessionRecord(overrides?: Partial<SessionRecord>): SessionRecord;
+export declare function tokenRecord(overrides?: Partial<TokenRecord>): TokenRecord;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/conformance/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/conformance/fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,MAAM,oBAAoB,CAAC;AAG5B;;;;GAIG;AAEH,eAAO,MAAM,EAAE,GAAI,KAAK,MAAM,KAAG,IAAqB,CAAC;AAKvD,wBAAgB,UAAU,CAAC,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,UAAU,CAmB1E;AAED,wBAAgB,aAAa,CAC5B,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GACpC,aAAa,CAWf;AAED,wBAAgB,WAAW,CAAC,SAAS,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAW7E"}

package/dist/conformance/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@nxgt/janus/conformance` — **what makes the port's contract checkable.**
+ *
+ * An adapter author runs this against their stores, and it fails an adapter
+ * that breaks one of the port's six rules — above all the one this package is
+ * built around: *an absence is `null`, a failure throws*. In an HTTP SDK that
+ * rule lives in one unwrapping function; in an embedded core it lives in the
+ * contract of the port, and this is where the contract is checked. That is why
+ * it is a published entry point, and not a page of documentation.
+ *
+ * Three layers, and the lowest depends on no test runner:
+ *
+ * - the cases, as data — `userStoreCases`, `sessionStoreCases`,
+ *   `tokenStoreCases`, `outageCases`, `allCases`;
+ * - `runCase`, which runs one against a harness;
+ * - `describeJanusStores`, which describes them all under bun:test, vitest
+ *   or jest.
+ *
+ * The same three for a relation store, the port `@nxgt/janus/permissions`
+ * reads: `relationStoreCases`, `relationOutageCases`, `allRelationCases`;
+ * `runRelationCase`; `describeRelationStores`.
+ *
+ * It imports no test framework and no assertion library.
+ */
+export { outageCases } from './cases/outage';
+export { sessionStoreCases } from './cases/sessions';
+export { tokenStoreCases } from './cases/tokens';
+export { userStoreCases } from './cases/users';
+export { allCases, describeJanusStores, runCase, SKIP_REASONS, } from './describe';
+export { referenceHarness } from './reference';
+export { allRelationCases, describeRelationStores, type OpenedRelations, type RelationCase, type RelationContext, type RelationFaults, type RelationHarness, type RelationMethod, referenceRelationHarness, relationOutageCases, relationStoreCases, runRelationCase, } from './relations';
+export type { CaseContext, ConformanceCase, ConformanceHarness, ConformanceRunner, OpenedStores, PortMethod, StoreFaults, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACN,QAAQ,EACR,mBAAmB,EACnB,OAAO,EACP,YAAY,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACN,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,GACX,MAAM,SAAS,CAAC"}