@zenstackhq/orm 3.4.6 → 3.5.0-beta.1

package/dist/index.d.cts

@@ -586,7 +586,8 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     plugins?: AnyPlugin[];
     /**
-     * Logging configuration.
+     * Logging configuration. Extends Kysely's log config with a `'warning'` level
+     * for ZenStack-specific diagnostics (e.g., slow query warnings).
      */
     log?: KyselyConfig['log'];
     /**
@@ -599,8 +600,11 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     fixPostgresTimezone?: boolean;
     /**
-     * Whether to enable input validations expressed with attributes like `@email`, `@regex`,
-     * `@@validate`, etc. Defaults to `true`.
+     * Whether to enable query args validation. Defaults to `true`.
+     *
+     * **USE WITH CAUTION**, as setting it to `false` will allow malformed input to pass through, causing
+     * incorrect SQL generation or runtime errors. If you use validation attributes like `@email`, `@regex`,
+     * etc., in ZModel, they will be ignored too.
      */
     validateInput?: boolean;
     /**
@@ -612,9 +616,23 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     useCompactAliasNames?: boolean;
     /**
-     * Whether to skip validation for computed fields.
+     * Whether to skip validation for whether all computed fields are properly defined.
      */
     skipValidationForComputedFields?: boolean;
+    /**
+     * Diagnostics related options.
+     */
+    diagnostics?: {
+        /**
+         * Threshold in milliseconds for determining slow queries. If not specified, no query will be considered slow.
+         */
+        slowQueryThresholdMs?: number;
+        /**
+         * Maximum number of slow query records to keep in memory. Defaults to `100`. When the number is exceeded, the
+         * entry with the lowest duration will be removed. Set to `Infinity` to keep unlimited records.
+         */
+        slowQueryMaxRecords?: number;
+    };
 } & (HasComputedFields<Schema> extends true ? {
     /**
      * Computed field definitions.
@@ -820,10 +838,17 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     protected abstract buildOrderByField(query: SelectQueryBuilder<any, any, any>, field: Expression<unknown>, sort: SortOrder, nulls: 'first' | 'last'): SelectQueryBuilder<any, any, any>;
 }
 
+type InputValidatorOptions = {
+    /**
+     * Whether validation is enabled. Defaults to `true`.
+     */
+    enabled?: boolean;
+};
 declare class InputValidator<Schema extends SchemaDef> {
     private readonly client;
     readonly zodFactory: ZodSchemaFactory<Schema>;
-    constructor(client: ClientContract<Schema>);
+    private readonly enabled;
+    constructor(client: ClientContract<Schema>, options?: InputValidatorOptions);
     validateFindArgs(model: GetModels<Schema>, args: unknown, operation: 'findFirst' | 'findUnique' | 'findMany'): FindArgs<Schema, GetModels<Schema>, any, true> | undefined;
     validateExistsArgs(model: GetModels<Schema>, args: unknown): ExistsArgs<Schema, GetModels<Schema>, any> | undefined;
     validateCreateArgs(model: GetModels<Schema>, args: unknown): CreateArgs<Schema, GetModels<Schema>, any>;
@@ -1999,6 +2024,50 @@ type ProviderSupportsDistinct<Schema extends SchemaDef> = Schema['provider']['ty
  */
 type ExtractExtQueryArgs<ExtQueryArgs, Operation extends CoreCrudOperations> = (Operation extends keyof ExtQueryArgs ? ExtQueryArgs[Operation] : {}) & ('$create' extends keyof ExtQueryArgs ? Operation extends CoreCreateOperations ? ExtQueryArgs['$create'] : {} : {}) & ('$read' extends keyof ExtQueryArgs ? (Operation extends CoreReadOperations ? ExtQueryArgs['$read'] : {}) : {}) & ('$update' extends keyof ExtQueryArgs ? Operation extends CoreUpdateOperations ? ExtQueryArgs['$update'] : {} : {}) & ('$delete' extends keyof ExtQueryArgs ? Operation extends CoreDeleteOperations ? ExtQueryArgs['$delete'] : {} : {}) & ('$all' extends keyof ExtQueryArgs ? ExtQueryArgs['$all'] : {});
 
+/**
+ * Zod schema cache statistics.
+ */
+interface ZodCacheStats {
+    /**
+     * Number of cached Zod schemas.
+     */
+    size: number;
+    /**
+     * Keys of the cached Zod schemas.
+     */
+    keys: string[];
+}
+/**
+ * Information about a query, used for diagnostics.
+ */
+interface QueryInfo {
+    /**
+     * Time when the query started.
+     */
+    startedAt: Date;
+    /**
+     * Duration of the query in milliseconds.
+     */
+    durationMs: number;
+    /**
+     * SQL statement of the query.
+     */
+    sql: string;
+}
+/**
+ * ZenStackClient diagnostics.
+ */
+interface Diagnostics {
+    /**
+     * Statistics about the Zod schemas (used for query args validation) cache.
+     */
+    zodCache: ZodCacheStats;
+    /**
+     * Slow queries.
+     */
+    slowQueries: QueryInfo[];
+}
+
 /**
  * A promise that only executes when it's awaited or .then() is called.
  */
@@ -2084,8 +2153,7 @@ type ClientContract<Schema extends SchemaDef, Options extends ClientOptions<Sche
      */
     $setOptions<NewOptions extends ClientOptions<Schema>>(options: NewOptions): ClientContract<Schema, NewOptions, ExtQueryArgs, ExtClientMembers>;
     /**
-     * Returns a new client enabling/disabling input validations expressed with attributes like
-     * `@email`, `@regex`, `@@validate`, etc.
+     * Returns a new client enabling/disabling query args validation.
      *
      * @deprecated Use {@link $setOptions} instead.
      */
@@ -2139,6 +2207,10 @@ type ClientContract<Schema extends SchemaDef, Options extends ClientOptions<Sche
      * @private
      */
     $pushSchema(): Promise<void>;
+    /**
+     * Returns diagnostics information such as cache and slow query statistics.
+     */
+    $diagnostics(): Promise<Diagnostics>;
 } & {
     [Key in GetSlicedModels<Schema, Options> as Uncapitalize<Key>]: ModelOperations<Schema, Key, Options, ExtQueryArgs>;
 } & ProcedureOperations<Schema, Options> & ExtClientMembers;
@@ -2739,15 +2811,18 @@ declare class ZodSchemaFactory<Schema extends SchemaDef, Options extends ClientO
     private readonly allFilterKinds;
     private readonly schema;
     private readonly options;
+    private readonly extraValidationsEnabled;
     constructor(client: ClientContract<Schema, Options, ExtQueryArgs, any>);
     constructor(schema: Schema, options?: Options);
     private get plugins();
-    private get extraValidationsEnabled();
     private shouldIncludeRelations;
     private nextOptions;
     private getCache;
     private setCache;
-    private printCacheStats;
+    get cacheStats(): {
+        size: number;
+        keys: string[];
+    };
     makeFindUniqueSchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindUniqueArgs<Schema, Model, Options, ExtQueryArgs>>;
     makeFindFirstSchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindFirstArgs<Schema, Model, Options, ExtQueryArgs> | undefined>;
     makeFindManySchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindManyArgs<Schema, Model, Options, ExtQueryArgs> | undefined>;

package/dist/index.d.ts

@@ -586,7 +586,8 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     plugins?: AnyPlugin[];
     /**
-     * Logging configuration.
+     * Logging configuration. Extends Kysely's log config with a `'warning'` level
+     * for ZenStack-specific diagnostics (e.g., slow query warnings).
      */
     log?: KyselyConfig['log'];
     /**
@@ -599,8 +600,11 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     fixPostgresTimezone?: boolean;
     /**
-     * Whether to enable input validations expressed with attributes like `@email`, `@regex`,
-     * `@@validate`, etc. Defaults to `true`.
+     * Whether to enable query args validation. Defaults to `true`.
+     *
+     * **USE WITH CAUTION**, as setting it to `false` will allow malformed input to pass through, causing
+     * incorrect SQL generation or runtime errors. If you use validation attributes like `@email`, `@regex`,
+     * etc., in ZModel, they will be ignored too.
      */
     validateInput?: boolean;
     /**
@@ -612,9 +616,23 @@ type ClientOptions<Schema extends SchemaDef> = QueryOptions<Schema> & {
      */
     useCompactAliasNames?: boolean;
     /**
-     * Whether to skip validation for computed fields.
+     * Whether to skip validation for whether all computed fields are properly defined.
      */
     skipValidationForComputedFields?: boolean;
+    /**
+     * Diagnostics related options.
+     */
+    diagnostics?: {
+        /**
+         * Threshold in milliseconds for determining slow queries. If not specified, no query will be considered slow.
+         */
+        slowQueryThresholdMs?: number;
+        /**
+         * Maximum number of slow query records to keep in memory. Defaults to `100`. When the number is exceeded, the
+         * entry with the lowest duration will be removed. Set to `Infinity` to keep unlimited records.
+         */
+        slowQueryMaxRecords?: number;
+    };
 } & (HasComputedFields<Schema> extends true ? {
     /**
      * Computed field definitions.
@@ -820,10 +838,17 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     protected abstract buildOrderByField(query: SelectQueryBuilder<any, any, any>, field: Expression<unknown>, sort: SortOrder, nulls: 'first' | 'last'): SelectQueryBuilder<any, any, any>;
 }
 
+type InputValidatorOptions = {
+    /**
+     * Whether validation is enabled. Defaults to `true`.
+     */
+    enabled?: boolean;
+};
 declare class InputValidator<Schema extends SchemaDef> {
     private readonly client;
     readonly zodFactory: ZodSchemaFactory<Schema>;
-    constructor(client: ClientContract<Schema>);
+    private readonly enabled;
+    constructor(client: ClientContract<Schema>, options?: InputValidatorOptions);
     validateFindArgs(model: GetModels<Schema>, args: unknown, operation: 'findFirst' | 'findUnique' | 'findMany'): FindArgs<Schema, GetModels<Schema>, any, true> | undefined;
     validateExistsArgs(model: GetModels<Schema>, args: unknown): ExistsArgs<Schema, GetModels<Schema>, any> | undefined;
     validateCreateArgs(model: GetModels<Schema>, args: unknown): CreateArgs<Schema, GetModels<Schema>, any>;
@@ -1999,6 +2024,50 @@ type ProviderSupportsDistinct<Schema extends SchemaDef> = Schema['provider']['ty
  */
 type ExtractExtQueryArgs<ExtQueryArgs, Operation extends CoreCrudOperations> = (Operation extends keyof ExtQueryArgs ? ExtQueryArgs[Operation] : {}) & ('$create' extends keyof ExtQueryArgs ? Operation extends CoreCreateOperations ? ExtQueryArgs['$create'] : {} : {}) & ('$read' extends keyof ExtQueryArgs ? (Operation extends CoreReadOperations ? ExtQueryArgs['$read'] : {}) : {}) & ('$update' extends keyof ExtQueryArgs ? Operation extends CoreUpdateOperations ? ExtQueryArgs['$update'] : {} : {}) & ('$delete' extends keyof ExtQueryArgs ? Operation extends CoreDeleteOperations ? ExtQueryArgs['$delete'] : {} : {}) & ('$all' extends keyof ExtQueryArgs ? ExtQueryArgs['$all'] : {});
 
+/**
+ * Zod schema cache statistics.
+ */
+interface ZodCacheStats {
+    /**
+     * Number of cached Zod schemas.
+     */
+    size: number;
+    /**
+     * Keys of the cached Zod schemas.
+     */
+    keys: string[];
+}
+/**
+ * Information about a query, used for diagnostics.
+ */
+interface QueryInfo {
+    /**
+     * Time when the query started.
+     */
+    startedAt: Date;
+    /**
+     * Duration of the query in milliseconds.
+     */
+    durationMs: number;
+    /**
+     * SQL statement of the query.
+     */
+    sql: string;
+}
+/**
+ * ZenStackClient diagnostics.
+ */
+interface Diagnostics {
+    /**
+     * Statistics about the Zod schemas (used for query args validation) cache.
+     */
+    zodCache: ZodCacheStats;
+    /**
+     * Slow queries.
+     */
+    slowQueries: QueryInfo[];
+}
+
 /**
  * A promise that only executes when it's awaited or .then() is called.
  */
@@ -2084,8 +2153,7 @@ type ClientContract<Schema extends SchemaDef, Options extends ClientOptions<Sche
      */
     $setOptions<NewOptions extends ClientOptions<Schema>>(options: NewOptions): ClientContract<Schema, NewOptions, ExtQueryArgs, ExtClientMembers>;
     /**
-     * Returns a new client enabling/disabling input validations expressed with attributes like
-     * `@email`, `@regex`, `@@validate`, etc.
+     * Returns a new client enabling/disabling query args validation.
      *
      * @deprecated Use {@link $setOptions} instead.
      */
@@ -2139,6 +2207,10 @@ type ClientContract<Schema extends SchemaDef, Options extends ClientOptions<Sche
      * @private
      */
     $pushSchema(): Promise<void>;
+    /**
+     * Returns diagnostics information such as cache and slow query statistics.
+     */
+    $diagnostics(): Promise<Diagnostics>;
 } & {
     [Key in GetSlicedModels<Schema, Options> as Uncapitalize<Key>]: ModelOperations<Schema, Key, Options, ExtQueryArgs>;
 } & ProcedureOperations<Schema, Options> & ExtClientMembers;
@@ -2739,15 +2811,18 @@ declare class ZodSchemaFactory<Schema extends SchemaDef, Options extends ClientO
     private readonly allFilterKinds;
     private readonly schema;
     private readonly options;
+    private readonly extraValidationsEnabled;
     constructor(client: ClientContract<Schema, Options, ExtQueryArgs, any>);
     constructor(schema: Schema, options?: Options);
     private get plugins();
-    private get extraValidationsEnabled();
     private shouldIncludeRelations;
     private nextOptions;
     private getCache;
     private setCache;
-    private printCacheStats;
+    get cacheStats(): {
+        size: number;
+        keys: string[];
+    };
     makeFindUniqueSchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindUniqueArgs<Schema, Model, Options, ExtQueryArgs>>;
     makeFindFirstSchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindFirstArgs<Schema, Model, Options, ExtQueryArgs> | undefined>;
     makeFindManySchema<Model extends GetModels<Schema>>(model: Model, options?: CreateSchemaOptions): ZodType<FindManyArgs<Schema, Model, Options, ExtQueryArgs> | undefined>;