Merge remote-tracking branch 'origin/dev' into multiple-files-fixes

Author: ymc9

.github/workflows/build-test.yml

@@ -8,6 +8,7 @@ on:
 
 env:
     TELEMETRY_TRACKING_TOKEN: ${{ secrets.TELEMETRY_TRACKING_TOKEN }}
+    VSCODE_TELEMETRY_TRACKING_TOKEN: ${{ secrets.VSCODE_TELEMETRY_TRACKING_TOKEN }}
     DO_NOT_TRACK: '1'
 
 permissions:

packages/cli/README.md

@@ -0,0 +1,24 @@
+# @zenstackhq/cli
+
+The command-line interface for ZenStack. Provides commands for initializing projects, generating TypeScript code from ZModel schemas, managing database migrations, and etc.
+
+## Key Commands
+
+- `zenstack init` — Initialize ZenStack in an existing project
+- `zenstack generate` — Compile ZModel schema to TypeScript
+- `zenstack db push` — Sync schema to the database
+- `zenstack db pull` — Pull database schema changes into ZModel
+- `zenstack migrate dev` — Create and apply database migrations
+- `zenstack migrate deploy` — Deploy migrations to production
+- `zenstack format` — Format ZModel schema files
+- `zenstack proxy|studio` — Start a database proxy server for using studio
+
+## Installation
+
+```bash
+npm install -D @zenstackhq/cli
+```
+
+## Learn More
+
+- [ZenStack Documentation](https://zenstack.dev/docs)

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

@@ -1,8 +1,28 @@
+import type { ClientContract, QueryOptions } from '@zenstackhq/orm';
+import type { SchemaDef } from '@zenstackhq/schema';
+
 /**
  * A type that represents either a value of type T or a Promise that resolves to type T.
  */
 export type MaybePromise<T> = T | Promise<T> | PromiseLike<T>;
 
+/**
+ * Infers the schema definition from a client contract type, or passes through a raw SchemaDef.
+ */
+export type InferSchema<T> = T extends { $schema: infer S extends SchemaDef } ? S : T extends SchemaDef ? T : never;
+
+/**
+ * Extracts the ExtResult type from a client contract, or defaults to `{}`.
+ */
+export type InferExtResult<T> = T extends ClientContract<any, any, any, any, infer E> ? E : {};
+
+/**
+ * Infers query options from a client contract type, or defaults to `QueryOptions<Schema>`.
+ */
+export type InferOptions<T, Schema extends SchemaDef> = T extends { $options: infer O extends QueryOptions<Schema> }
+    ? O
+    : QueryOptions<Schema>;
+
 /**
  * List of ORM write actions.
  */

packages/clients/tanstack-query/src/common/types.ts

@@ -3,11 +3,12 @@ import type { FetchFn } from '@zenstackhq/client-helpers/fetch';
 import type {
     GetProcedureNames,
     GetSlicedOperations,
-    OperationsIneligibleForDelegateModels,
+    ModelAllowsCreate,
+    OperationsRequiringCreate,
     ProcedureFunc,
     QueryOptions,
 } from '@zenstackhq/orm';
-import type { GetModels, IsDelegateModel, SchemaDef } from '@zenstackhq/schema';
+import type { GetModels, SchemaDef } from '@zenstackhq/schema';
 
 /**
  * Context type for configuring the hooks.
@@ -59,8 +60,8 @@ export type ExtraMutationOptions = {
     optimisticDataProvider?: OptimisticDataProvider;
 } & QueryContext;
 
-type HooksOperationsIneligibleForDelegateModels = OperationsIneligibleForDelegateModels extends any
-    ? `use${Capitalize<OperationsIneligibleForDelegateModels>}`
+type HooksOperationsRequiringCreate = OperationsRequiringCreate extends any
+    ? `use${Capitalize<OperationsRequiringCreate>}`
     : never;
 
 type Modifiers = '' | 'Suspense' | 'Infinite' | 'SuspenseInfinite';
@@ -76,12 +77,12 @@ export type TrimSlicedOperations<
 > = {
     // trim operations based on slicing options
     [Key in keyof T as Key extends `use${Modifiers}${Capitalize<GetSlicedOperations<Schema, Model, Options>>}`
-        ? IsDelegateModel<Schema, Model> extends true
-            ? // trim operations ineligible for delegate models
-              Key extends HooksOperationsIneligibleForDelegateModels
-                ? never
-                : Key
-            : Key
+        ? ModelAllowsCreate<Schema, Model> extends true
+            ? Key
+            : // trim create operations for models that don't allow create
+              Key extends HooksOperationsRequiringCreate
+              ? never
+              : Key
         : never]: T[Key];
 };
 

packages/clients/tanstack-query/src/react.ts

@@ -19,6 +19,9 @@ import {
     createInvalidator,
     createOptimisticUpdater,
     DEFAULT_QUERY_ENDPOINT,
+    type InferExtResult,
+    type InferOptions,
+    type InferSchema,
     type InvalidationPredicate,
 } from '@zenstackhq/client-helpers';
 import { fetcher, makeUrl, marshal } from '@zenstackhq/client-helpers/fetch';
@@ -27,6 +30,7 @@ import type {
     AggregateArgs,
     AggregateResult,
     BatchResult,
+    ClientContract,
     CountArgs,
     CountResult,
     CreateArgs,
@@ -35,6 +39,7 @@ import type {
     DeleteArgs,
     DeleteManyArgs,
     ExistsArgs,
+    ExtResultBase,
     FindFirstArgs,
     FindManyArgs,
     FindUniqueArgs,
@@ -69,6 +74,8 @@ import type {
     WithOptimistic,
 } from '../common/types.js';
 export type { FetchFn } from '@zenstackhq/client-helpers/fetch';
+export type { InferExtResult, InferOptions, InferSchema } from '@zenstackhq/client-helpers';
+export type { SchemaDef } from '@zenstackhq/schema';
 
 type ProcedureHookFn<
     Schema extends SchemaDef,
@@ -139,15 +146,20 @@ export type ModelMutationModelResult<
     TArgs,
     Array extends boolean = false,
     Options extends QueryOptions<Schema> = QueryOptions<Schema>,
-> = Omit<ModelMutationResult<SimplifiedResult<Schema, Model, TArgs, Options, false, Array>, TArgs>, 'mutateAsync'> & {
+    ExtResult extends ExtResultBase<Schema> = {},
+> = Omit<ModelMutationResult<SimplifiedResult<Schema, Model, TArgs, Options, false, Array, ExtResult>, TArgs>, 'mutateAsync'> & {
     mutateAsync<T extends TArgs>(
         args: T,
-        options?: ModelMutationOptions<SimplifiedResult<Schema, Model, T, Options, false, Array>, T>,
-    ): Promise<SimplifiedResult<Schema, Model, T, Options, false, Array>>;
+        options?: ModelMutationOptions<SimplifiedResult<Schema, Model, T, Options, false, Array, ExtResult>, T>,
+    ): Promise<SimplifiedResult<Schema, Model, T, Options, false, Array, ExtResult>>;
 };
 
-export type ClientHooks<Schema extends SchemaDef, Options extends QueryOptions<Schema> = QueryOptions<Schema>> = {
-    [Model in GetSlicedModels<Schema, Options> as `${Uncapitalize<Model>}`]: ModelQueryHooks<Schema, Model, Options>;
+export type ClientHooks<
+    Schema extends SchemaDef,
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtResult extends ExtResultBase<Schema> = {},
+> = {
+    [Model in GetSlicedModels<Schema, Options> as `${Uncapitalize<Model>}`]: ModelQueryHooks<Schema, Model, Options, ExtResult>;
 } & ProcedureHooks<Schema, Options>;
 
 type ProcedureHookGroup<Schema extends SchemaDef, Options extends QueryOptions<Schema>> = {
@@ -200,65 +212,66 @@ export type ModelQueryHooks<
     Schema extends SchemaDef,
     Model extends GetModels<Schema>,
     Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtResult extends ExtResultBase<Schema> = {},
 > = TrimSlicedOperations<
     Schema,
     Model,
     Options,
     {
-        useFindUnique<T extends FindUniqueArgs<Schema, Model, Options>>(
-            args: Accessor<SelectSubset<T, FindUniqueArgs<Schema, Model, Options>>>,
-            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options> | null>>,
-        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options> | null>;
+        useFindUnique<T extends FindUniqueArgs<Schema, Model, Options, {}, ExtResult>>(
+            args: Accessor<SelectSubset<T, FindUniqueArgs<Schema, Model, Options, {}, ExtResult>>>,
+            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult> | null>>,
+        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult> | null>;
 
-        useFindFirst<T extends FindFirstArgs<Schema, Model, Options>>(
-            args?: Accessor<SelectSubset<T, FindFirstArgs<Schema, Model, Options>>>,
-            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options> | null>>,
-        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options> | null>;
+        useFindFirst<T extends FindFirstArgs<Schema, Model, Options, {}, ExtResult>>(
+            args?: Accessor<SelectSubset<T, FindFirstArgs<Schema, Model, Options, {}, ExtResult>>>,
+            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult> | null>>,
+        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult> | null>;
 
         useExists<T extends ExistsArgs<Schema, Model, Options>>(
             args?: Accessor<Subset<T, ExistsArgs<Schema, Model, Options>>>,
             options?: Accessor<ModelQueryOptions<boolean>>,
         ): ModelQueryResult<boolean>;
 
-        useFindMany<T extends FindManyArgs<Schema, Model, Options>>(
-            args?: Accessor<SelectSubset<T, FindManyArgs<Schema, Model, Options>>>,
-            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options>[]>>,
-        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options>[]>;
+        useFindMany<T extends FindManyArgs<Schema, Model, Options, {}, ExtResult>>(
+            args?: Accessor<SelectSubset<T, FindManyArgs<Schema, Model, Options, {}, ExtResult>>>,
+            options?: Accessor<ModelQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[]>>,
+        ): ModelQueryResult<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[]>;
 
-        useInfiniteFindMany<T extends FindManyArgs<Schema, Model, Options>>(
-            args?: Accessor<SelectSubset<T, FindManyArgs<Schema, Model, Options>>>,
-            options?: Accessor<ModelInfiniteQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options>[]>>,
-        ): ModelInfiniteQueryResult<InfiniteData<SimplifiedPlainResult<Schema, Model, T, Options>[]>>;
+        useInfiniteFindMany<T extends FindManyArgs<Schema, Model, Options, {}, ExtResult>>(
+            args?: Accessor<SelectSubset<T, FindManyArgs<Schema, Model, Options, {}, ExtResult>>>,
+            options?: Accessor<ModelInfiniteQueryOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[]>>,
+        ): ModelInfiniteQueryResult<InfiniteData<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[]>>;
 
-        useCreate<T extends CreateArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>, T>>,
-        ): ModelMutationModelResult<Schema, Model, T, false, Options>;
+        useCreate<T extends CreateArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>, T>>,
+        ): ModelMutationModelResult<Schema, Model, T, false, Options, ExtResult>;
 
         useCreateMany<T extends CreateManyArgs<Schema, Model>>(
             options?: Accessor<ModelMutationOptions<BatchResult, T>>,
         ): ModelMutationResult<BatchResult, T>;
 
-        useCreateManyAndReturn<T extends CreateManyAndReturnArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>[], T>>,
-        ): ModelMutationModelResult<Schema, Model, T, true, Options>;
+        useCreateManyAndReturn<T extends CreateManyAndReturnArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[], T>>,
+        ): ModelMutationModelResult<Schema, Model, T, true, Options, ExtResult>;
 
-        useUpdate<T extends UpdateArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>, T>>,
-        ): ModelMutationModelResult<Schema, Model, T, false, Options>;
+        useUpdate<T extends UpdateArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>, T>>,
+        ): ModelMutationModelResult<Schema, Model, T, false, Options, ExtResult>;
         useUpdateMany<T extends UpdateManyArgs<Schema, Model, Options>>(
             options?: Accessor<ModelMutationOptions<BatchResult, T>>,
         ): ModelMutationResult<BatchResult, T>;
 
-        useUpdateManyAndReturn<T extends UpdateManyAndReturnArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>[], T>>,
-        ): ModelMutationModelResult<Schema, Model, T, true, Options>;
+        useUpdateManyAndReturn<T extends UpdateManyAndReturnArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>[], T>>,
+        ): ModelMutationModelResult<Schema, Model, T, true, Options, ExtResult>;
 
-        useUpsert<T extends UpsertArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>, T>>,
-        ): ModelMutationModelResult<Schema, Model, T, false, Options>;
-        useDelete<T extends DeleteArgs<Schema, Model, Options>>(
-            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options>, T>>,
-        ): ModelMutationModelResult<Schema, Model, T, false, Options>;
+        useUpsert<T extends UpsertArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>, T>>,
+        ): ModelMutationModelResult<Schema, Model, T, false, Options, ExtResult>;
+        useDelete<T extends DeleteArgs<Schema, Model, Options, {}, ExtResult>>(
+            options?: Accessor<ModelMutationOptions<SimplifiedPlainResult<Schema, Model, T, Options, ExtResult>, T>>,
+        ): ModelMutationModelResult<Schema, Model, T, false, Options, ExtResult>;
 
         useDeleteMany<T extends DeleteManyArgs<Schema, Model, Options>>(
             options?: Accessor<ModelMutationOptions<BatchResult, T>>,
@@ -283,21 +296,36 @@ export type ModelQueryHooks<
 
 /**
  * Gets data query hooks for all models in the schema.
+ *
+ * Accepts either a raw `SchemaDef` or a `ClientContract` type (e.g. `typeof db`) as the generic parameter.
+ * When a `ClientContract` type is provided, computed fields from plugins are reflected in the result types.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with schema
+ * const client = useClientQueries(schema)
+ *
+ * // With server client type for computed field support
+ * import type { DbType } from '~/server/db'
+ * const client = useClientQueries<DbType>(schema)
+ * ```
  */
-export function useClientQueries<Schema extends SchemaDef, Options extends QueryOptions<Schema> = QueryOptions<Schema>>(
-    schema: Schema,
+export function useClientQueries<
+    SchemaOrClient extends SchemaDef | ClientContract<any, any, any, any, any>,
+>(
+    schema: InferSchema<SchemaOrClient>,
     options?: Accessor<QueryContext>,
-): ClientHooks<Schema, Options> {
+): ClientHooks<InferSchema<SchemaOrClient>, InferOptions<SchemaOrClient, InferSchema<SchemaOrClient>>, InferExtResult<SchemaOrClient> extends ExtResultBase<InferSchema<SchemaOrClient>> ? InferExtResult<SchemaOrClient> : {}> {
     const result = Object.keys(schema.models).reduce(
         (acc, model) => {
-            (acc as any)[lowerCaseFirst(model)] = useModelQueries<Schema, GetModels<Schema>, Options>(
-                schema,
-                model as GetModels<Schema>,
+            (acc as any)[lowerCaseFirst(model)] = useModelQueries(
+                schema as any,
+                model as any,
                 options,
             );
             return acc;
         },
-        {} as ClientHooks<Schema, Options>,
+        {} as any,
     );
 
     const procedures = (schema as any).procedures as Record<string, { mutation?: boolean }> | undefined;
@@ -347,7 +375,8 @@ export function useModelQueries<
     Schema extends SchemaDef,
     Model extends GetModels<Schema>,
     Options extends QueryOptions<Schema>,
->(schema: Schema, model: Model, rootOptions?: Accessor<QueryContext>): ModelQueryHooks<Schema, Model, Options> {
+    ExtResult extends ExtResultBase<Schema> = {},
+>(schema: Schema, model: Model, rootOptions?: Accessor<QueryContext>): ModelQueryHooks<Schema, Model, Options, ExtResult> {
     const modelDef = Object.values(schema.models).find((m) => m.name.toLowerCase() === model.toLowerCase());
     if (!modelDef) {
         throw new Error(`Model "${model}" not found in schema`);
@@ -423,7 +452,7 @@ export function useModelQueries<
         useGroupBy: (args: any, options?: any) => {
             return useInternalQuery(schema, modelName, 'groupBy', args, options);
         },
-    } as unknown as ModelQueryHooks<Schema, Model, Options>;
+    } as unknown as ModelQueryHooks<Schema, Model, Options, ExtResult>;
 }
 
 export function useInternalQuery<TQueryFnData, TData>(