hysteria-orm 10.4.3 → 10.4.4

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> {
@@ -3466,6 +3561,210 @@ declare class ModelQueryBuilder<T extends Model, A extends Record<string, any> =
     annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): ModelQueryBuilder<T, A & {
         [P in K]: V;
     }, R>;
+    /**
+     * @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 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
+     * const user = await User.query().selectJson("data", "user.name", "userName").first();
+     * console.log(user?.$annotations?.userName); // Typed as any
+     * ```
+     */
+    selectJson<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
+    selectJson<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
+    /**
+     * @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 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
+     * const user = await User.query().selectJsonText("data", "user.email", "email").first();
+     * console.log(user?.$annotations?.email); // Typed as string
+     * ```
+     */
+    selectJsonText<K extends string>(column: ModelKey<T>, path: any, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: string;
+    }, R>;
+    selectJsonText<K extends string>(column: string, path: any, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: string;
+    }, R>;
+    /**
+     * @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]
+     * @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
+     * 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): ModelQueryBuilder<T, A & {
+        [P in K]: number;
+    }, R>;
+    selectJsonArrayLength<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: number;
+    }, R>;
+    /**
+     * @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]
+     * @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
+     * 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): ModelQueryBuilder<T, A & {
+        [P in K]: any[];
+    }, R>;
+    selectJsonKeys<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any[];
+    }, R>;
+    /**
+     * @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 Result will be available in model.$annotations[alias]
+     * @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
+     * const user = await User.query().selectJsonRaw("data->>'email'", "email").first();
+     * console.log(user?.$annotations?.email); // Typed as any
+     * ```
+     */
+    selectJsonRaw<K extends string>(raw: string, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
     /**
      * @description Removes annotations from the serialized model, by default, annotations are maintained in the serialized model if `annotate` is used
      */

package/lib/index.d.ts

@@ -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> {
@@ -3466,6 +3561,210 @@ declare class ModelQueryBuilder<T extends Model, A extends Record<string, any> =
     annotate<K extends string, S extends SqlMethod, V = CommonSqlMethodReturnType<S>>(sqlMethod: S, column: string, alias: K): ModelQueryBuilder<T, A & {
         [P in K]: V;
     }, R>;
+    /**
+     * @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 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
+     * const user = await User.query().selectJson("data", "user.name", "userName").first();
+     * console.log(user?.$annotations?.userName); // Typed as any
+     * ```
+     */
+    selectJson<K extends string>(column: ModelKey<T>, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
+    selectJson<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
+    /**
+     * @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 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
+     * const user = await User.query().selectJsonText("data", "user.email", "email").first();
+     * console.log(user?.$annotations?.email); // Typed as string
+     * ```
+     */
+    selectJsonText<K extends string>(column: ModelKey<T>, path: any, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: string;
+    }, R>;
+    selectJsonText<K extends string>(column: string, path: any, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: string;
+    }, R>;
+    /**
+     * @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]
+     * @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
+     * 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): ModelQueryBuilder<T, A & {
+        [P in K]: number;
+    }, R>;
+    selectJsonArrayLength<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: number;
+    }, R>;
+    /**
+     * @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]
+     * @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
+     * 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): ModelQueryBuilder<T, A & {
+        [P in K]: any[];
+    }, R>;
+    selectJsonKeys<K extends string>(column: string, path: JsonPathInput, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any[];
+    }, R>;
+    /**
+     * @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 Result will be available in model.$annotations[alias]
+     * @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
+     * const user = await User.query().selectJsonRaw("data->>'email'", "email").first();
+     * console.log(user?.$annotations?.email); // Typed as any
+     * ```
+     */
+    selectJsonRaw<K extends string>(raw: string, alias: K): ModelQueryBuilder<T, A & {
+        [P in K]: any;
+    }, R>;
     /**
      * @description Removes annotations from the serialized model, by default, annotations are maintained in the serialized model if `annotate` is used
      */