hysteria-orm 10.4.3 → 10.4.5

package/lib/index.d.cts

@@ -2279,6 +2279,8 @@ declare class WhereGroupNode extends QueryNode {
     constructor(nodes: (WhereNode | WhereGroupNode | WhereSubqueryNode)[], chainsWith?: "and" | "or");
 }
 
+type JsonPathInput = string | (string | number)[];
+
 declare class DistinctNode extends QueryNode {
     chainsWith: string;
     canKeywordBeSeenMultipleTimes: boolean;
@@ -2786,9 +2788,9 @@ declare class SelectQueryBuilder<T extends Model> extends JoinQueryBuilder<T> {
      * const user = await User.query().annotate("id", "superId").first(); // id as superId
      * ```
      */
-    annotate(column: string, alias: string): this;
-    annotate(sqlMethod: SqlMethod, column: string, alias: string): this;
-    annotate(sqlMethod: string, column: string, alias: string): this;
+    annotate<A extends string>(column: string, alias: A): this;
+    annotate<A extends string>(sqlMethod: SqlMethod, column: string, alias: A): this;
+    annotate<A extends string>(sqlMethod: string, column: string, alias: A): this;
     /**
      * @description Sets the table to select from, by default is the table defined in the Model
      * @description Can be used on non select queries too, it will only specify the table name (es. INSERT INTO $table)
@@ -2812,6 +2814,99 @@ declare class SelectQueryBuilder<T extends Model> extends JoinQueryBuilder<T> {
      */
     distinctOn(...columns: ModelKey<T>[]): this;
     distinctOn<S extends string>(...columns: SelectableColumn<S>[]): this;
+    /**
+     * @description Selects a JSON value at the specified path and returns it as JSON
+     * @param column The column containing JSON data
+     * @param path The JSON path to extract (standardized format: "$.user.name", "user.name", or ["user", "name"])
+     * @param alias The alias for the selected value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description Result will be available in model.$annotations[alias]
+     * @example
+     * ```ts
+     * // All databases accept the same path format:
+     * const user = await User.query().selectJson("data", "$.user.name", "userName").first();
+     * console.log(user?.$annotations?.userName); // Typed!
+     *
+     * await User.query().selectJson("data", "user.name", "userName").first(); // $ is optional
+     * await User.query().selectJson("data", ["user", "name"], "userName").first();
+     *
+     * // Array indices:
+     * await User.query().selectJson("data", "items.0.name", "firstItemName").first();
+     * await User.query().selectJson("data", ["items", 0, "name"], "firstItemName").first();
+     * ```
+     */
+    selectJson<A extends string>(column: ModelKey<T>, path: JsonPathInput, alias: A): this;
+    selectJson<A extends string>(column: string, path: JsonPathInput, alias: A): this;
+    /**
+     * @description Selects a JSON value at the specified path and returns it as text
+     * @param column The column containing JSON data
+     * @param path The JSON path to extract (standardized format)
+     * @param alias The alias for the selected value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description Result will be available in model.$annotations[alias]
+     * @example
+     * ```ts
+     * // All databases accept the same path format:
+     * const user = await User.query().selectJsonText("data", "$.user.name", "userName").first();
+     * console.log(user?.$annotations?.userName); // Typed!
+     *
+     * await User.query().selectJsonText("data", ["user", "name"], "userName").first();
+     * ```
+     */
+    selectJsonText<A extends string>(column: ModelKey<T>, path: JsonPathInput, alias: A): this;
+    selectJsonText<A extends string>(column: string, path: JsonPathInput, alias: A): this;
+    /**
+     * @description Selects the length of a JSON array
+     * @param column The column containing JSON array data
+     * @param path The JSON path to the array (standardized format, use "$" or "" for root)
+     * @param alias The alias for the length value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description Result will be available in model.$annotations[alias]
+     * @example
+     * ```ts
+     * // All databases accept the same path format:
+     * const user = await User.query().selectJsonArrayLength("data", "$.items", "itemCount").first();
+     * console.log(user?.$annotations?.itemCount); // Typed!
+     *
+     * await User.query().selectJsonArrayLength("data", "items", "itemCount").first();
+     * await User.query().selectJsonArrayLength("data", "$", "totalCount").first(); // root array
+     * ```
+     */
+    selectJsonArrayLength<A extends string>(column: ModelKey<T>, path: JsonPathInput, alias: A): this;
+    selectJsonArrayLength<A extends string>(column: string, path: JsonPathInput, alias: A): this;
+    /**
+     * @description Selects the keys of a JSON object
+     * @param column The column containing JSON object data
+     * @param path The JSON path to the object (standardized format, use "$" or "" for root)
+     * @param alias The alias for the keys
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description Result will be available in model.$annotations[alias]
+     * @postgres Returns an array of keys
+     * @mysql Returns a JSON array of keys
+     * @example
+     * ```ts
+     * // All databases accept the same path format:
+     * const user = await User.query().selectJsonKeys("data", "$.user", "userKeys").first();
+     * console.log(user?.$annotations?.userKeys); // Typed!
+     *
+     * await User.query().selectJsonKeys("data", "user", "userKeys").first();
+     * await User.query().selectJsonKeys("data", "$", "rootKeys").first(); // root object
+     * ```
+     */
+    selectJsonKeys<A extends string>(column: ModelKey<T>, path: JsonPathInput, alias: A): this;
+    selectJsonKeys<A extends string>(column: string, path: JsonPathInput, alias: A): this;
+    /**
+     * @description Adds a raw JSON select expression
+     * @param raw The raw SQL expression
+     * @param alias The alias for the selected value
+     * @description Result will be available in model.$annotations[alias]
+     * @example
+     * ```ts
+     * const user = await User.query().selectJsonRaw("data->>'email'", "userEmail").first();
+     * console.log(user?.$annotations?.userEmail); // Typed!
+     * ```
+     */
+    selectJsonRaw<A extends string>(raw: string, alias: A): this;
 }
 
 declare abstract class WhereQueryBuilder<T extends Model> extends SelectQueryBuilder<T> {
@@ -3323,6 +3418,16 @@ type UpdateOptions = {
  */
 type RelationQueryBuilderType<T extends Model, A extends Record<string, any> = {}, R extends Record<string, any> = {}> = Omit<ModelQueryBuilder<T, A, R>, "increment" | "decrement" | "first" | "firstOrFail" | "paginate" | "pluck" | "truncate" | "many" | "one" | "oneOrFail" | "insert" | "insertMany" | "update" | "delete" | "softDelete" | "getSum" | "getAvg" | "getMin" | "getMax" | "getCount" | "getMin" | "getMax" | "getCount">;
 
+/**
+ * Helper type to determine if annotation overrides model field or goes to $annotations
+ * If K is a key of the model T, it overrides that field in the model.
+ * Otherwise, it goes into the annotations object A.
+ */
+type AnnotationResult<T extends Model, A extends Record<string, any>, R extends Record<string, any>, K extends string, V> = K extends keyof T ? ModelQueryBuilder<T & {
+    [P in K]: V;
+}, A, R> : ModelQueryBuilder<T, A & {
+    [P in K]: V;
+}, R>;
 declare class ModelQueryBuilder<T extends Model, A extends Record<string, any> = {}, R extends Record<string, any> = {}> extends QueryBuilder<T> {
     relation: Relation;
     protected sqlModelManagerUtils: SqlModelManagerUtils<T>;
@@ -3417,11 +3522,11 @@ declare class ModelQueryBuilder<T extends Model, A extends Record<string, any> =
     /**
      * @description Inserts a new record into the database, it is not advised to use this method directly from the query builder if using a ModelQueryBuilder (`Model.query()`), use the `Model.insert` method instead.
      */
-    insert(...args: Parameters<typeof this$1.model.insert>): ReturnType<typeof this$1.model.insert>;
+    insert(...args: Parameters<typeof this$1.model.insert<T>>): ReturnType<typeof this$1.model.insert>;
     /**
      * @description Inserts multiple records into the database, it is not advised to use this method directly from the query builder if using a ModelQueryBuilder (`Model.query()`), use the `Model.insertMany` method instead.
      */
-    insertMany(...args: Parameters<typeof this$1.model.insertMany>): ReturnType<typeof this$1.model.insertMany>;
+    insertMany(...args: Parameters<typeof this$1.model.insertMany<T>>): ReturnType<typeof this$1.model.insertMany>;
     update(data: Partial<ModelWithoutRelations<T>>, options?: UpdateOptions): Promise<number>;
     softDelete(options?: SoftDeleteOptions<T>): Promise<number>;
     delete(options?: DeleteOptions): Promise<number>;
@@ -3447,25 +3552,209 @@ declare class ModelQueryBuilder<T extends Model, A extends Record<string, any> =
     select(...columns: (ModelKey<T> | "*")[]): this;
     /**
      * @description Annotates a column with a SQL method or a simple alias
-     * @description If using a model, the result will be available in the $annotations property of the model, else it will be available in the result of the query
+     * @description If the alias matches a model field name, it overrides that field. Otherwise, it's available in $annotations
      * @example
      * ```ts
      * const user = await User.query().annotate("max", "id", "maxId").first(); // max(id) as maxId
      * const user = await User.query().annotate("id", "superId").first(); // id as superId
+     * // If alias matches model field, it overrides it:
+     * const user = await User.query().annotate("COUNT(*)", "email").first(); // user.email is now a number
      * ```
      */
-    annotate<K extends string, V = any>(column: string, alias: K): ModelQueryBuilder<T, A & {
-        [P in K]: V;
-    }, R>;
-    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: string, column: string, alias: K): ModelQueryBuilder<T, A & {
-        [P in K]: V;
-    }, R>;
-    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): ModelQueryBuilder<T, A & {
-        [P in K]: V;
-    }, R>;
-    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): ModelQueryBuilder<T, A & {
-        [P in K]: V;
-    }, R>;
+    annotate<K extends string, V = any>(column: string, alias: K): AnnotationResult<T, A, R, K, V>;
+    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: string, column: string, alias: K): AnnotationResult<T, A, R, K, V>;
+    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): AnnotationResult<T, A, R, K, V>;
+    annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): AnnotationResult<T, A, R, K, V>;
+    /**
+     * @description Selects a JSON value at the specified path and returns it as JSON
+     * @param column The column containing JSON data
+     * @param path The JSON path to extract (standardized format: "$.user.name", "user.name", or ["user", "name"])
+     * @param alias The alias for the selected value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description If alias matches a model field, it overrides that field. Otherwise, it's in $annotations
+     * @example
+     * ```ts
+     * // All these path formats are supported:
+     *
+     * // 1. With $ prefix (standard JSON path)
+     * await User.query().selectJson("data", "$.user.name", "userName").first();
+     *
+     * // 2. Without $ prefix ($ is optional)
+     * await User.query().selectJson("data", "user.name", "userName").first();
+     *
+     * // 3. Array format
+     * await User.query().selectJson("data", ["user", "name"], "userName").first();
+     *
+     * // 4. Array indices with dot notation
+     * await User.query().selectJson("data", "items.0.name", "firstItemName").first();
+     *
+     * // 5. Array indices with array format
+     * await User.query().selectJson("data", ["items", 0, "name"], "firstItemName").first();
+     *
+     * // 6. Root object
+     * await User.query().selectJson("data", "$", "allData").first();
+     *
+     * // Access the result - in $annotations if not a model field
+     * const user = await User.query().selectJson("data", "user.name", "userName").first();
+     * console.log(user?.$annotations?.userName); // Typed as any
+     *
+     * // If alias matches model field, it overrides it
+     * const user2 = await User.query().selectJson("data", "$.name", "email").first();
+     * console.log(user2?.email); // Overrides model's email field
+     * ```
+     */
+    selectJson<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, any>;
+    selectJson<K extends string>(column: string, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, any>;
+    /**
+     * @description Selects a JSON value at the specified path and returns it as text
+     * @param column The column containing JSON data
+     * @param path The JSON path to extract (standardized format)
+     * @param alias The alias for the selected value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description If alias matches a model field, it overrides that field. Otherwise, it's in $annotations
+     * @example
+     * ```ts
+     * // All these path formats are supported:
+     *
+     * // 1. With $ prefix
+     * await User.query().selectJsonText("data", "$.user.email", "userEmail").first();
+     *
+     * // 2. Without $ prefix
+     * await User.query().selectJsonText("data", "user.email", "userEmail").first();
+     *
+     * // 3. Array format
+     * await User.query().selectJsonText("data", ["user", "email"], "userEmail").first();
+     *
+     * // 4. Array indices
+     * await User.query().selectJsonText("data", "tags.0", "firstTag").first();
+     * await User.query().selectJsonText("data", ["tags", 0], "firstTag").first();
+     *
+     * // 5. Deep nesting
+     * await User.query().selectJsonText("data", "user.profile.bio", "biography").first();
+     *
+     * // Access the result - in $annotations if not a model field
+     * const user = await User.query().selectJsonText("data", "user.email", "userEmail").first();
+     * console.log(user?.$annotations?.userEmail); // Typed as string
+     * ```
+     */
+    selectJsonText<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, string>;
+    selectJsonText<K extends string>(column: string, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, string>;
+    /**
+     * @description Selects the length of a JSON array
+     * @param column The column containing JSON array data
+     * @param path The JSON path to the array (standardized format, use "$" or "" for root)
+     * @param alias The alias for the length value
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description If alias matches a model field, it overrides that field. Otherwise, it's in $annotations
+     * @warning Not supported in SQLite
+     * @example
+     * ```ts
+     * // All these path formats are supported:
+     *
+     * // 1. With $ prefix
+     * await User.query().selectJsonArrayLength("data", "$.items", "itemCount").first();
+     *
+     * // 2. Without $ prefix
+     * await User.query().selectJsonArrayLength("data", "items", "itemCount").first();
+     *
+     * // 3. Array format
+     * await User.query().selectJsonArrayLength("data", ["items"], "itemCount").first();
+     *
+     * // 4. Root array (use "$" or "")
+     * await User.query().selectJsonArrayLength("data", "$", "totalCount").first();
+     * await User.query().selectJsonArrayLength("data", "", "totalCount").first();
+     *
+     * // 5. Nested arrays
+     * await User.query().selectJsonArrayLength("data", "user.roles", "roleCount").first();
+     * await User.query().selectJsonArrayLength("data", ["user", "roles"], "roleCount").first();
+     *
+     * // 6. Deeply nested arrays
+     * await User.query().selectJsonArrayLength("data", "level1.level2.items", "deepCount").first();
+     *
+     * // Access the result - in $annotations if not a model field
+     * const user = await User.query().selectJsonArrayLength("data", "items", "count").first();
+     * console.log(user?.$annotations?.count); // Typed as number
+     * ```
+     */
+    selectJsonArrayLength<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, number>;
+    selectJsonArrayLength<K extends string>(column: string, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, number>;
+    /**
+     * @description Selects the keys of a JSON object
+     * @param column The column containing JSON object data
+     * @param path The JSON path to the object (standardized format, use "$" or "" for root)
+     * @param alias The alias for the keys
+     * @description Path format is standardized across all databases - ORM converts to DB-specific syntax
+     * @description If alias matches a model field, it overrides that field. Otherwise, it's in $annotations
+     * @warning Not supported in SQLite or MSSQL
+     * @postgresql Returns a native array of keys
+     * @mysql Returns a JSON array of keys
+     * @example
+     * ```ts
+     * // All these path formats are supported:
+     *
+     * // 1. With $ prefix
+     * await User.query().selectJsonKeys("data", "$.settings", "settingKeys").first();
+     *
+     * // 2. Without $ prefix
+     * await User.query().selectJsonKeys("data", "settings", "settingKeys").first();
+     *
+     * // 3. Array format
+     * await User.query().selectJsonKeys("data", ["settings"], "settingKeys").first();
+     *
+     * // 4. Root object (use "$" or "")
+     * await User.query().selectJsonKeys("data", "$", "rootKeys").first();
+     * await User.query().selectJsonKeys("data", "", "rootKeys").first();
+     *
+     * // 5. Nested objects
+     * await User.query().selectJsonKeys("data", "user.profile", "profileKeys").first();
+     * await User.query().selectJsonKeys("data", ["user", "profile"], "profileKeys").first();
+     *
+     * // 6. Deeply nested objects
+     * await User.query().selectJsonKeys("data", "settings.display.theme", "themeKeys").first();
+     *
+     * // Access the result - in $annotations if not a model field
+     * const user = await User.query().selectJsonKeys("data", "settings", "keys").first();
+     * console.log(user?.$annotations?.keys); // Typed as any[] - ["theme", "fontSize", "autoSave"]
+     * ```
+     */
+    selectJsonKeys<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, any[]>;
+    selectJsonKeys<K extends string>(column: string, path: JsonPathInput, alias: K): AnnotationResult<T, A, R, K, any[]>;
+    /**
+     * @description Adds a raw JSON select expression for database-specific operations
+     * @param raw The raw SQL expression (database-specific syntax)
+     * @param alias The alias for the selected value
+     * @description If alias matches a model field, it overrides that field. Otherwise, it's in $annotations
+     * @description Use this for advanced JSON operations not covered by other selectJson* methods
+     * @warning This bypasses path standardization - you must write database-specific SQL
+     * @example
+     * ```ts
+     * // PostgreSQL - Extract as text with ->> operator
+     * await User.query().selectJsonRaw("data->>'email'", "userEmail").first();
+     *
+     * // PostgreSQL - Extract nested JSON with -> operator
+     * await User.query().selectJsonRaw("data->'user'->'profile'->>'name'", "profileName").first();
+     *
+     * // PostgreSQL - Array element access
+     * await User.query().selectJsonRaw("data->'items'->0->>'name'", "firstName").first();
+     *
+     * // MySQL - Extract value with JSON_EXTRACT and ->>
+     * await User.query().selectJsonRaw("data->>'$.email'", "userEmail").first();
+     *
+     * // MySQL - Array length with JSON_LENGTH
+     * await User.query().selectJsonRaw("JSON_LENGTH(data, '$.items')", "itemCount").first();
+     *
+     * // MSSQL - Extract value with JSON_VALUE
+     * await User.query().selectJsonRaw("JSON_VALUE(data, '$.email')", "userEmail").first();
+     *
+     * // SQLite - Extract value with json_extract
+     * await User.query().selectJsonRaw("json_extract(data, '$.email')", "userEmail").first();
+     *
+     * // Access the result - in $annotations if not a model field
+     * const user = await User.query().selectJsonRaw("data->>'email'", "userEmail").first();
+     * console.log(user?.$annotations?.userEmail); // Typed as any
+     * ```
+     */
+    selectJsonRaw<K extends string>(raw: string, alias: K): AnnotationResult<T, A, R, K, any>;
     /**
      * @description Removes annotations from the serialized model, by default, annotations are maintained in the serialized model if `annotate` is used
      */
@@ -4230,7 +4519,7 @@ declare class SqlDataSource<D extends SqlDataSourceType = SqlDataSourceType, T e
     private connectWithoutSettingPrimary;
 }
 
-type ModelWithoutRelations<T extends Model> = Pick<T, ExcludeRelations<Omit<T, "*">>>;
+type ModelWithoutRelations<T extends Model> = Pick<Omit<T, "*">, ExcludeRelations<Omit<T, "*">>> & Pick<Model, keyof Model>;
 type NumberModelKey<T extends Model> = {
     [K in keyof T]: T[K] extends number | bigint ? K : never;
 }[keyof T];
@@ -5077,6 +5366,12 @@ declare abstract class Model extends Entity {
      * @throws {HysteriaError} If the model has no primary key valorized in the instance
      */
     refresh<T extends Model = this>(options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<T>;
+    /**
+     * @description Converts the model to a JSON object
+     * @description Flattens all `$annotations` into the JSON object at first level including the relations
+     * @warning Use with caution, this method flattens the `$annotations` into the JSON object at first level including the relations, so if you have conflicting column names between model columns and annotations, the annotation could override the model column value
+     */
+    toJSON(): Record<string, any>;
 }
 
 type BaseModelRelationType = {