@silkline/hasura-sim 0.1.1 → 0.1.3

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@silkline/hasura-sim",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "In-memory Hasura GraphQL Engine (compiled to WebAssembly) + pglite — runs real GraphQL queries/mutations offline for tests and codegen, with no Docker/Postgres/network.",
   "type": "module",
   "main": "src/index.mjs",
+  "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
   },
   "files": [
     "src",

package/src/index.d.ts

@@ -0,0 +1,130 @@
+import type { PGliteInterface } from '@electric-sql/pglite';
+import type {
+  GraphQLFieldResolver,
+  GraphQLFormattedError,
+  IntrospectionQuery,
+} from 'graphql';
+
+export { PGlite } from '@electric-sql/pglite';
+
+/** Arguments to a single GraphQL execution. */
+export interface ExecuteArgs {
+  query: string;
+  variables?: Record<string, unknown>;
+  /** x-hasura-role; defaults to `admin` (bypasses permissions). */
+  role?: string;
+  /** x-hasura-* session variables, e.g. { 'x-hasura-org-id': '…' }. */
+  sessionVariables?: Record<string, string>;
+}
+
+/** Result of a GraphQL execution: the engine's `{ data, errors }` payload. */
+export interface ExecuteResult<TData = Record<string, unknown>> {
+  data?: TData | null;
+  errors?: readonly GraphQLFormattedError[];
+}
+
+/** A graphql-js resolver map: `{ [typeName]: { [fieldName]: resolver } }`. */
+export type RemoteResolvers = Record<
+  string,
+  Record<string, GraphQLFieldResolver<unknown, unknown>>
+>;
+
+/**
+ * A remote schema, supplied as a static SDL string or as an object carrying the
+ * SDL (for schema-cache build) plus optional mock execution — either field
+ * `resolvers` (run with graphql-js over the SDL) or a whole-operation
+ * `handler`. `{ introspection }` accepts a pre-computed introspection response.
+ */
+export type RemoteSchemaDef =
+  | string
+  | {
+      sdl: string;
+      resolvers?: RemoteResolvers;
+      handler?: (op: {
+        query: string;
+        variables?: Record<string, unknown>;
+      }) => ExecuteResult | Promise<ExecuteResult>;
+    }
+  | { introspection: unknown };
+
+/** Context passed to an action handler alongside its arguments. */
+export interface ActionHandlerContext {
+  /** x-hasura-* session variables from the request. */
+  sessionVariables: Record<string, string>;
+  /** The raw Hasura action webhook payload. */
+  payload: unknown;
+}
+
+/**
+ * Handler for a Hasura action. `args` is the action's arguments object (keyed
+ * by your argument names, e.g. `{ input }`).
+ */
+export type ActionHandler<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> = (args: TArgs, context: ActionHandlerContext) => TResult | Promise<TResult>;
+
+export interface CreateSimulatorArgs {
+  /** Consolidated Hasura metadata ({ version, sources, … }). */
+  metadataJson?: unknown;
+  /** A pglite instance to run SQL against; one is created if omitted. */
+  db?: PGliteInterface;
+  /** Remote schemas, keyed by remote-schema name. */
+  remoteSchemas?: Record<string, RemoteSchemaDef>;
+  /** Action handlers, keyed by action name. */
+  actions?: Record<string, ActionHandler>;
+}
+
+/** Result of `sim_init`; `error` is set if metadata/schema-cache build failed. */
+export interface InitResult {
+  error?: string;
+}
+
+export interface RoleArgs {
+  /** x-hasura-role to scope the schema/operation to. */
+  role?: string;
+  /** x-hasura-* session variables the role expects. */
+  sessionVariables?: Record<string, string>;
+}
+
+/** A running simulator: a wasm Hasura engine bound to a pglite database. */
+export interface Simulator {
+  /** The pglite database the engine executes SQL against. */
+  db: PGliteInterface;
+  /** (Re)build the schema cache from metadata + static remote introspections. */
+  init(
+    metadata: unknown,
+    remoteSchemas?: Record<string, RemoteSchemaDef>,
+  ): Promise<InitResult>;
+  /** The engine's version string. */
+  version(): Promise<string>;
+  /** Execute a GraphQL operation and return `{ data, errors }`. */
+  execute<TData = Record<string, unknown>>(
+    args: ExecuteArgs,
+  ): Promise<ExecuteResult<TData>>;
+  /** Run standard GraphQL introspection for a role. */
+  introspect(args?: RoleArgs): Promise<IntrospectionQuery>;
+  /** Role-scoped schema as SDL — a static codegen base, generated offline. */
+  schemaSDL(args?: RoleArgs): Promise<string>;
+}
+
+/**
+ * Create an in-memory Hasura simulator: the real GraphQL Engine v2 compiled to
+ * WebAssembly, executing SQL against pglite. If `metadataJson` is provided the
+ * schema cache is built eagerly; otherwise call `init()` yourself.
+ */
+export function createSimulator(args?: CreateSimulatorArgs): Promise<Simulator>;
+
+/**
+ * Run one Haskell-bridge request against a pglite connection via the raw wire
+ * protocol. Exported for tests; normally reached through the wasm bridge.
+ */
+export function execOnPglite(db: PGliteInterface, requestJson: string): Promise<string>;
+
+/**
+ * Normalise a remote-schema definition to the introspection *response* shape
+ * the engine expects (`{ data: { __schema: … } }`).
+ */
+export function remoteSchemaToIntrospection(def: RemoteSchemaDef): {
+  data: { __schema: IntrospectionQuery['__schema'] };
+};