feat(fetch-client): implement fetch-based CRUD API client

packages/clients/client-helpers/src/constants.ts

@@ -1,4 +1,9 @@
 /**
- * The default query endpoint.
+ * Route segment used for custom procedures.
  */
-export const DEFAULT_QUERY_ENDPOINT = '/api/model';
+export const CUSTOM_PROC_ROUTE_NAME = '$procs';
+
+/**
+ * Route prefix used for transactions.
+ */
+export const TRANSACTION_ROUTE_PREFIX = '$transaction';

packages/clients/client-helpers/src/index.ts

@@ -7,4 +7,5 @@ export * from './nested-read-visitor';
 export * from './nested-write-visitor';
 export * from './optimistic';
 export * from './query-analysis';
+export * from './transaction';
 export * from './types';

packages/clients/client-helpers/src/transaction.ts

@@ -0,0 +1,70 @@
+import type {
+    CoreCrudOperations,
+    CrudArgsMap,
+    CrudReturnMap,
+    ExtQueryArgsBase,
+    ExtResultBase,
+    GetSlicedOperations,
+    ModelAllowsCreate,
+    OperationsRequiringCreate,
+    QueryOptions,
+} from '@zenstackhq/orm';
+import type { GetModels, SchemaDef } from '@zenstackhq/schema';
+
+/**
+ * Operations available in a sequential transaction.
+ */
+type AllowedTransactionOps<
+    Schema extends SchemaDef,
+    Model extends GetModels<Schema>,
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+> =
+    ModelAllowsCreate<Schema, Model> extends true
+        ? GetSlicedOperations<Schema, Model, Options> & CoreCrudOperations
+        : Exclude<GetSlicedOperations<Schema, Model, Options> & CoreCrudOperations, OperationsRequiringCreate>;
+
+/**
+ * Represents a single operation to execute within a sequential transaction.
+ *
+ * The `model`, `op`, and `args` fields are correlated: `op` is constrained to
+ * the CRUD operations available on `model` (respecting `Options['slicing']`), and
+ * `args` is typed accordingly.
+ */
+export type TransactionOperation<
+    Schema extends SchemaDef,
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtQueryArgs extends ExtQueryArgsBase = {},
+    ExtResult extends ExtResultBase<Schema> = {},
+> = {
+    [Model in GetModels<Schema>]: {
+        [Op in AllowedTransactionOps<Schema, Model, Options>]: {} extends CrudArgsMap<
+            Schema,
+            Model,
+            Options,
+            ExtQueryArgs,
+            ExtResult
+        >[Op]
+            ? { model: Model; op: Op; args?: CrudArgsMap<Schema, Model, Options, ExtQueryArgs, ExtResult>[Op] }
+            : { model: Model; op: Op; args: CrudArgsMap<Schema, Model, Options, ExtQueryArgs, ExtResult>[Op] };
+    }[AllowedTransactionOps<Schema, Model, Options>];
+}[GetModels<Schema>];
+
+/**
+ * Maps each operation in a transaction tuple to its precise result type, preserving
+ * per-position typing.
+ */
+export type TransactionResults<
+    Schema extends SchemaDef,
+    Ops extends readonly TransactionOperation<Schema, any, any, any>[],
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtResult extends ExtResultBase<Schema> = {},
+> = {
+    [K in keyof Ops]: Ops[K] extends { model: infer M; op: infer O; args?: infer A }
+        ? M extends GetModels<Schema>
+            ? O extends keyof CrudReturnMap<Schema, M, A, Options, ExtResult>
+                ? CrudReturnMap<Schema, M, A, Options, ExtResult>[O]
+                : never
+            : never
+        : never;
+};
+

packages/clients/fetch-client/eslint.config.js

@@ -0,0 +1,4 @@
+import config from '@zenstackhq/eslint-config/base.js';
+
+/** @type {import("eslint").Linter.Config} */
+export default config;

packages/clients/fetch-client/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@zenstackhq/fetch-client",
+    "displayName": "ZenStack Fetch Client",
+    "description": "Simple fetch-based client for consuming ZenStack's RPC-style CRUD API",
+    "version": "3.6.4",
+    "type": "module",
+    "author": {
+        "name": "ZenStack Team",
+        "email": "contact@zenstack.dev"
+    },
+    "homepage": "https://zenstack.dev",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/zenstackhq/zenstack"
+    },
+    "license": "MIT",
+    "scripts": {
+        "build": "tsc --noEmit && tsdown && pnpm test:generate && pnpm test:typecheck",
+        "watch": "tsdown --watch",
+        "lint": "eslint src --ext ts",
+        "test": "vitest run",
+        "test:generate": "tsx ../../../scripts/test-generate.ts test --lite-only",
+        "test:typecheck": "tsc --noEmit --project tsconfig.test.json",
+        "pack": "pnpm pack"
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "default": "./dist/index.mjs"
+        }
+    },
+    "dependencies": {
+        "@zenstackhq/client-helpers": "workspace:*",
+        "@zenstackhq/common-helpers": "workspace:*",
+        "@zenstackhq/orm": "workspace:*",
+        "@zenstackhq/schema": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/node": "catalog:",
+        "@zenstackhq/cli": "workspace:*",
+        "@zenstackhq/eslint-config": "workspace:*",
+        "@zenstackhq/tsdown-config": "workspace:*",
+        "@zenstackhq/typescript-config": "workspace:*",
+        "@zenstackhq/vitest-config": "workspace:*",
+        "decimal.js": "catalog:"
+    },
+    "funding": "https://github.com/sponsors/zenstackhq"
+}