supabase-typed-query 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -1
- package/dist/index.d.ts +989 -2
- package/dist/index.js +2 -1219
- package/dist/index.js.map +1 -1
- package/package.json +39 -36
- package/dist/index.mjs +0 -1211
- package/dist/index.mjs.map +0 -1
- package/dist/src/entity/Entity.d.ts +0 -29
- package/dist/src/entity/Entity.d.ts.map +0 -1
- package/dist/src/entity/PartitionedEntity.d.ts +0 -31
- package/dist/src/entity/PartitionedEntity.d.ts.map +0 -1
- package/dist/src/entity/core.d.ts +0 -123
- package/dist/src/entity/core.d.ts.map +0 -1
- package/dist/src/entity/index.d.ts +0 -5
- package/dist/src/entity/index.d.ts.map +0 -1
- package/dist/src/entity/types.d.ts +0 -168
- package/dist/src/entity/types.d.ts.map +0 -1
- package/dist/src/index.d.ts +0 -14
- package/dist/src/index.d.ts.map +0 -1
- package/dist/src/query/Query.d.ts +0 -189
- package/dist/src/query/Query.d.ts.map +0 -1
- package/dist/src/query/QueryBuilder.d.ts +0 -28
- package/dist/src/query/QueryBuilder.d.ts.map +0 -1
- package/dist/src/query/index.d.ts +0 -171
- package/dist/src/query/index.d.ts.map +0 -1
- package/dist/src/query/rpc.d.ts +0 -87
- package/dist/src/query/rpc.d.ts.map +0 -1
- package/dist/src/types.d.ts +0 -223
- package/dist/src/types.d.ts.map +0 -1
- package/dist/src/utils/errors.d.ts +0 -27
- package/dist/src/utils/errors.d.ts.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,989 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
import { Brand, IO, IOTask, IOTask as Task, List, List as List$1, Option, Option as Option$1 } from "functype";
|
|
2
|
+
|
|
3
|
+
//#region src/types.d.ts
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Core type definitions for supabase-typed-query
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Structure of a single schema within a database.
|
|
10
|
+
*/
|
|
11
|
+
interface SchemaDefinition {
|
|
12
|
+
Tables: Record<string, {
|
|
13
|
+
Row: object;
|
|
14
|
+
Insert: object;
|
|
15
|
+
Update: object;
|
|
16
|
+
}>;
|
|
17
|
+
Views?: Record<string, {
|
|
18
|
+
Row: object;
|
|
19
|
+
}>;
|
|
20
|
+
Functions?: Record<string, {
|
|
21
|
+
Args: object;
|
|
22
|
+
Returns: unknown;
|
|
23
|
+
}>;
|
|
24
|
+
Enums?: Record<string, unknown>;
|
|
25
|
+
CompositeTypes?: Record<string, unknown>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Base schema interface that all databases must conform to.
|
|
29
|
+
* Consumer-provided Database types must extend this interface.
|
|
30
|
+
* Supports multiple schemas (public, custom schemas, etc.)
|
|
31
|
+
*
|
|
32
|
+
* Note: No index signature - TypeScript's structural typing allows additional properties.
|
|
33
|
+
* This permits Supabase's __InternalSupabase while maintaining type safety for valid schemas.
|
|
34
|
+
*/
|
|
35
|
+
interface DatabaseSchema {
|
|
36
|
+
public: SchemaDefinition;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Extracts a valid schema from a database type.
|
|
40
|
+
* Returns the schema if it's a valid SchemaDefinition, otherwise never.
|
|
41
|
+
* This ensures type-safe access to schema properties.
|
|
42
|
+
*/
|
|
43
|
+
type ValidSchema<DB extends DatabaseSchema, S extends string> = S extends keyof DB ? DB[S] extends SchemaDefinition ? DB[S] : never : never;
|
|
44
|
+
/**
|
|
45
|
+
* Helper type to strip `__InternalSupabase` from Supabase-generated database types.
|
|
46
|
+
* Following Supabase's own pattern from SupabaseClient.
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* ```typescript
|
|
50
|
+
* type Schemas = keyof TypedDatabase<Database> // "public" | "inventory" (excludes __InternalSupabase)
|
|
51
|
+
* ```
|
|
52
|
+
*/
|
|
53
|
+
type TypedDatabase<DB> = Omit<DB, "__InternalSupabase">;
|
|
54
|
+
/**
|
|
55
|
+
* Default Database type - used as fallback when no specific database type is provided.
|
|
56
|
+
* For proper type inference, consumers should pass their generated Database type as a generic.
|
|
57
|
+
*/
|
|
58
|
+
interface Database extends DatabaseSchema {
|
|
59
|
+
public: {
|
|
60
|
+
Tables: Record<string, {
|
|
61
|
+
Row: Record<string, unknown>;
|
|
62
|
+
Insert: Record<string, unknown>;
|
|
63
|
+
Update: Record<string, unknown>;
|
|
64
|
+
}>;
|
|
65
|
+
Views: Record<string, {
|
|
66
|
+
Row: Record<string, unknown>;
|
|
67
|
+
}>;
|
|
68
|
+
Functions: Record<string, {
|
|
69
|
+
Args: Record<string, unknown>;
|
|
70
|
+
Returns: unknown;
|
|
71
|
+
}>;
|
|
72
|
+
Enums: Record<string, unknown>;
|
|
73
|
+
CompositeTypes: Record<string, unknown>;
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Schema names for a given database.
|
|
78
|
+
* Only includes keys whose values are valid SchemaDefinitions (have Tables property).
|
|
79
|
+
* This excludes __InternalSupabase by structure, not just by name - providing true type safety.
|
|
80
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
81
|
+
*/
|
|
82
|
+
type SchemaNames<DB extends DatabaseSchema = Database> = { [K in keyof DB]: DB[K] extends SchemaDefinition ? K : never }[keyof DB] & string;
|
|
83
|
+
/**
|
|
84
|
+
* Table names for a given database schema.
|
|
85
|
+
* Uses ValidSchema for type-safe access - only valid SchemaDefinitions can be accessed.
|
|
86
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
87
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
88
|
+
*/
|
|
89
|
+
type TableNames<DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = keyof ValidSchema<DB, S>["Tables"] & string;
|
|
90
|
+
/**
|
|
91
|
+
* Row type for a given table in a database schema.
|
|
92
|
+
* Uses ValidSchema for type-safe access.
|
|
93
|
+
* @typeParam T - The table name
|
|
94
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
95
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
96
|
+
*/
|
|
97
|
+
type TableRow<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Tables"][T]["Row"];
|
|
98
|
+
/**
|
|
99
|
+
* Insert type for a given table in a database schema.
|
|
100
|
+
* Uses ValidSchema for type-safe access.
|
|
101
|
+
* @typeParam T - The table name
|
|
102
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
103
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
104
|
+
*/
|
|
105
|
+
type TableInsert<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Tables"][T]["Insert"];
|
|
106
|
+
/**
|
|
107
|
+
* Update type for a given table in a database schema.
|
|
108
|
+
* Uses ValidSchema for type-safe access.
|
|
109
|
+
* @typeParam T - The table name
|
|
110
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
111
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
112
|
+
*/
|
|
113
|
+
type TableUpdate<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Tables"][T]["Update"];
|
|
114
|
+
/**
|
|
115
|
+
* View names for a given database schema.
|
|
116
|
+
* Uses ValidSchema for type-safe access - only valid SchemaDefinitions can be accessed.
|
|
117
|
+
* Views are read-only and only have a Row type (no Insert/Update).
|
|
118
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
119
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
120
|
+
*/
|
|
121
|
+
type ViewNames<DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Views"] extends Record<string, {
|
|
122
|
+
Row: object;
|
|
123
|
+
}> ? keyof ValidSchema<DB, S>["Views"] & string : never;
|
|
124
|
+
/**
|
|
125
|
+
* Row type for a given view in a database schema.
|
|
126
|
+
* Views are read-only, so they only have a Row type (no Insert or Update).
|
|
127
|
+
* Uses ValidSchema for type-safe access.
|
|
128
|
+
* @typeParam V - The view name
|
|
129
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
130
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
131
|
+
*/
|
|
132
|
+
type ViewRow<V extends ViewNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Views"] extends Record<string, {
|
|
133
|
+
Row: object;
|
|
134
|
+
}> ? ValidSchema<DB, S>["Views"][V]["Row"] : never;
|
|
135
|
+
/**
|
|
136
|
+
* Function names for a given database schema.
|
|
137
|
+
* Extracts the keys from the Functions record in the schema definition.
|
|
138
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
139
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
140
|
+
*/
|
|
141
|
+
type FunctionNames<DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Functions"] extends Record<string, unknown> ? keyof ValidSchema<DB, S>["Functions"] & string : never;
|
|
142
|
+
/**
|
|
143
|
+
* Argument type for a given function in a database schema.
|
|
144
|
+
* @typeParam F - The function name
|
|
145
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
146
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
147
|
+
*/
|
|
148
|
+
type FunctionArgs<F extends FunctionNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Functions"] extends Record<string, {
|
|
149
|
+
Args: unknown;
|
|
150
|
+
Returns: unknown;
|
|
151
|
+
}> ? ValidSchema<DB, S>["Functions"][F]["Args"] : never;
|
|
152
|
+
/**
|
|
153
|
+
* Return type for a given function in a database schema.
|
|
154
|
+
* @typeParam F - The function name
|
|
155
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
156
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
157
|
+
*/
|
|
158
|
+
type FunctionReturns<F extends FunctionNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = ValidSchema<DB, S>["Functions"] extends Record<string, {
|
|
159
|
+
Args: unknown;
|
|
160
|
+
Returns: unknown;
|
|
161
|
+
}> ? ValidSchema<DB, S>["Functions"][F]["Returns"] : never;
|
|
162
|
+
type EmptyObject = Record<string, never>;
|
|
163
|
+
interface QueryBuilder extends Promise<{
|
|
164
|
+
data: unknown;
|
|
165
|
+
error: unknown;
|
|
166
|
+
}> {
|
|
167
|
+
select: (columns?: string) => QueryBuilder;
|
|
168
|
+
insert: (data: unknown) => QueryBuilder;
|
|
169
|
+
update: (data: unknown) => QueryBuilder;
|
|
170
|
+
upsert: (data: unknown, options?: {
|
|
171
|
+
onConflict?: string;
|
|
172
|
+
}) => QueryBuilder;
|
|
173
|
+
delete: () => QueryBuilder;
|
|
174
|
+
match: (query: Record<string, unknown>) => QueryBuilder;
|
|
175
|
+
eq: (column: string, value: unknown) => QueryBuilder;
|
|
176
|
+
neq: (column: string, value: unknown) => QueryBuilder;
|
|
177
|
+
gt: (column: string, value: unknown) => QueryBuilder;
|
|
178
|
+
gte: (column: string, value: unknown) => QueryBuilder;
|
|
179
|
+
lt: (column: string, value: unknown) => QueryBuilder;
|
|
180
|
+
lte: (column: string, value: unknown) => QueryBuilder;
|
|
181
|
+
like: (column: string, pattern: string) => QueryBuilder;
|
|
182
|
+
ilike: (column: string, pattern: string) => QueryBuilder;
|
|
183
|
+
is: (column: string, value: boolean | null) => QueryBuilder;
|
|
184
|
+
in: (column: string, values: unknown[]) => QueryBuilder;
|
|
185
|
+
or: (filters: string) => QueryBuilder;
|
|
186
|
+
single: () => QueryBuilder;
|
|
187
|
+
limit: (count: number) => QueryBuilder;
|
|
188
|
+
order: (column: string, options?: {
|
|
189
|
+
ascending?: boolean;
|
|
190
|
+
}) => QueryBuilder;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* RPC query builder returned by client.rpc()
|
|
194
|
+
*/
|
|
195
|
+
interface RpcQueryBuilder extends Promise<{
|
|
196
|
+
data: unknown;
|
|
197
|
+
error: unknown;
|
|
198
|
+
}> {
|
|
199
|
+
select: (columns?: string) => RpcQueryBuilder;
|
|
200
|
+
single: () => RpcQueryBuilder;
|
|
201
|
+
limit: (count: number) => RpcQueryBuilder;
|
|
202
|
+
order: (column: string, options?: {
|
|
203
|
+
ascending?: boolean;
|
|
204
|
+
}) => RpcQueryBuilder;
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Supabase client type - accepts any client with compatible from(), schema(), and rpc() methods.
|
|
208
|
+
* Uses `unknown` return type to allow SupabaseClient<Database> from @supabase/supabase-js
|
|
209
|
+
* to be used directly without type casting.
|
|
210
|
+
*
|
|
211
|
+
* This interface is intentionally permissive to accept Supabase clients configured for
|
|
212
|
+
* different schemas (e.g., SupabaseClient<Database, "public", "custom_schema">).
|
|
213
|
+
* The Entity/PartitionedEntity functions use their own schema type parameter for type safety.
|
|
214
|
+
*
|
|
215
|
+
* Note: The DB type parameter is unused but kept for API consistency and future extensibility.
|
|
216
|
+
*
|
|
217
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
218
|
+
*/
|
|
219
|
+
interface SupabaseClientType<_DB extends DatabaseSchema = Database> {
|
|
220
|
+
from: (table: any) => any;
|
|
221
|
+
schema: (name: any) => any;
|
|
222
|
+
rpc: (...args: any[]) => any;
|
|
223
|
+
}
|
|
224
|
+
//#endregion
|
|
225
|
+
//#region src/query/Query.d.ts
|
|
226
|
+
type ComparisonOperators<V> = {
|
|
227
|
+
gte?: V;
|
|
228
|
+
gt?: V;
|
|
229
|
+
lte?: V;
|
|
230
|
+
lt?: V;
|
|
231
|
+
neq?: V;
|
|
232
|
+
like?: string;
|
|
233
|
+
ilike?: string;
|
|
234
|
+
in?: V[];
|
|
235
|
+
is?: null | boolean;
|
|
236
|
+
};
|
|
237
|
+
type WhereConditions<T extends object> = Partial<{ [K in keyof T]: T[K] | null | ComparisonOperators<T[K]> }> & {
|
|
238
|
+
gte?: Partial<{ [K in keyof T]?: T[K] }>;
|
|
239
|
+
gt?: Partial<{ [K in keyof T]?: T[K] }>;
|
|
240
|
+
lte?: Partial<{ [K in keyof T]?: T[K] }>;
|
|
241
|
+
lt?: Partial<{ [K in keyof T]?: T[K] }>;
|
|
242
|
+
neq?: Partial<{ [K in keyof T]?: T[K] }>;
|
|
243
|
+
like?: Partial<{ [K in keyof T]?: Extract<T[K], string> }>;
|
|
244
|
+
ilike?: Partial<{ [K in keyof T]?: Extract<T[K], string> }>;
|
|
245
|
+
};
|
|
246
|
+
/**
|
|
247
|
+
* Entity-specific WHERE conditions - no nested ComparisonOperators allowed.
|
|
248
|
+
* Entity API methods (getItems, updateItem, etc.) don't process nested operators.
|
|
249
|
+
* Use separate `is`, `wherein`, etc. parameters for these operations.
|
|
250
|
+
*
|
|
251
|
+
* @example
|
|
252
|
+
* // Correct Entity usage:
|
|
253
|
+
* Entity.getItems({ where: { code }, is: { used_at: null } })
|
|
254
|
+
*
|
|
255
|
+
* // Incorrect (use Query API instead for nested operators):
|
|
256
|
+
* Entity.getItems({ where: { code, used_at: { is: null } } }) // TypeScript error
|
|
257
|
+
*/
|
|
258
|
+
type EntityWhereConditions<T extends object> = Partial<{ [K in keyof T]: T[K] | null }>;
|
|
259
|
+
type IsConditions<T extends object = EmptyObject> = Partial<Record<keyof T, null | boolean>>;
|
|
260
|
+
type NotConditions<T extends object = EmptyObject> = {
|
|
261
|
+
is?: Partial<Record<keyof T, null | boolean>>;
|
|
262
|
+
in?: Partial<Record<keyof T, unknown[]>>;
|
|
263
|
+
};
|
|
264
|
+
type SoftDeleteMode = "include" | "exclude" | "only";
|
|
265
|
+
/**
|
|
266
|
+
* Base execution interface that all database operations implement
|
|
267
|
+
*/
|
|
268
|
+
interface ExecutableQuery<T> {
|
|
269
|
+
execute(): IOTask<Error, T>;
|
|
270
|
+
executeOrThrow(): Promise<T>;
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Standard interface for operations that return a single result
|
|
274
|
+
*/
|
|
275
|
+
interface SingleExecution<T> extends ExecutableQuery<Option$1<T>> {
|
|
276
|
+
one(): IOTask<Error, Option$1<T>>;
|
|
277
|
+
oneOrThrow(): Promise<T>;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Standard interface for operations that return multiple results
|
|
281
|
+
*/
|
|
282
|
+
interface MultiExecution<T> extends ExecutableQuery<List$1<T>> {
|
|
283
|
+
many(): IOTask<Error, List$1<T>>;
|
|
284
|
+
manyOrThrow(): Promise<List$1<T>>;
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* Core Query interface with branded type support.
|
|
288
|
+
* Simplified to take just the Row type for better TypeScript performance.
|
|
289
|
+
*
|
|
290
|
+
* @typeParam Row - The row type for the table
|
|
291
|
+
*/
|
|
292
|
+
interface Query<Row extends object> {
|
|
293
|
+
one(): IOTask<Error, Option$1<Row>>;
|
|
294
|
+
many(): IOTask<Error, List$1<Row>>;
|
|
295
|
+
first(): IOTask<Error, Option$1<Row>>;
|
|
296
|
+
oneOrThrow(): Promise<Row>;
|
|
297
|
+
manyOrThrow(): Promise<List$1<Row>>;
|
|
298
|
+
firstOrThrow(): Promise<Row>;
|
|
299
|
+
or(where: WhereConditions<Row>, is?: IsConditions<Row>): Query<Row>;
|
|
300
|
+
whereId<ID extends Brand<string, string>>(id: ID): Query<Row>;
|
|
301
|
+
orWhereId<ID extends Brand<string, string>>(id: ID): Query<Row>;
|
|
302
|
+
map<U>(fn: (item: Row) => U): MappedQuery<U>;
|
|
303
|
+
filter(predicate: (item: Row) => boolean): Query<Row>;
|
|
304
|
+
limit(count: number): Query<Row>;
|
|
305
|
+
offset(count: number): Query<Row>;
|
|
306
|
+
includeDeleted(): Query<Row>;
|
|
307
|
+
excludeDeleted(): Query<Row>;
|
|
308
|
+
onlyDeleted(): Query<Row>;
|
|
309
|
+
}
|
|
310
|
+
interface MappedQuery<U> {
|
|
311
|
+
one(): IOTask<Error, Option$1<U>>;
|
|
312
|
+
many(): IOTask<Error, List$1<U>>;
|
|
313
|
+
first(): IOTask<Error, Option$1<U>>;
|
|
314
|
+
oneOrThrow(): Promise<U>;
|
|
315
|
+
manyOrThrow(): Promise<List$1<U>>;
|
|
316
|
+
firstOrThrow(): Promise<U>;
|
|
317
|
+
map<V>(fn: (item: U) => V): MappedQuery<V>;
|
|
318
|
+
filter(predicate: (item: U) => boolean): MappedQuery<U>;
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* Query condition for internal state management with type-safe where.
|
|
322
|
+
*
|
|
323
|
+
* @typeParam Row - The row type
|
|
324
|
+
*/
|
|
325
|
+
interface QueryCondition<Row extends object> {
|
|
326
|
+
where: WhereConditions<Row>;
|
|
327
|
+
is?: IsConditions<Row>;
|
|
328
|
+
wherein?: Partial<Record<keyof Row, unknown[]>>;
|
|
329
|
+
gt?: Partial<Record<keyof Row, number | string | Date>>;
|
|
330
|
+
gte?: Partial<Record<keyof Row, number | string | Date>>;
|
|
331
|
+
lt?: Partial<Record<keyof Row, number | string | Date>>;
|
|
332
|
+
lte?: Partial<Record<keyof Row, number | string | Date>>;
|
|
333
|
+
neq?: Partial<Record<keyof Row, unknown>>;
|
|
334
|
+
like?: Partial<Record<keyof Row, string>>;
|
|
335
|
+
ilike?: Partial<Record<keyof Row, string>>;
|
|
336
|
+
not?: NotConditions<Row>;
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Entity-specific query interfaces for better type safety.
|
|
340
|
+
*
|
|
341
|
+
* @typeParam Row - The row type
|
|
342
|
+
*/
|
|
343
|
+
interface EntityQuery<Row extends object> extends Query<Row> {
|
|
344
|
+
normalize(): NormalizedQuery<Row>;
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* Normalized query interface.
|
|
348
|
+
*
|
|
349
|
+
* @typeParam Row - The row type
|
|
350
|
+
*/
|
|
351
|
+
interface NormalizedQuery<Row extends object> {
|
|
352
|
+
one(): IOTask<Error, Option$1<Row>>;
|
|
353
|
+
many(): IOTask<Error, List$1<Row>>;
|
|
354
|
+
first(): IOTask<Error, Option$1<Row>>;
|
|
355
|
+
}
|
|
356
|
+
declare const isQuery: <Row extends object>(obj: unknown) => obj is Query<Row>;
|
|
357
|
+
declare const isMappedQuery: <U>(obj: unknown) => obj is MappedQuery<U>;
|
|
358
|
+
/**
|
|
359
|
+
* Utility types for query parameters with type safety.
|
|
360
|
+
* Simplified to take Row type directly.
|
|
361
|
+
*
|
|
362
|
+
* @typeParam Row - The row type
|
|
363
|
+
*/
|
|
364
|
+
type QueryWhereParams<Row extends object> = WhereConditions<Row>;
|
|
365
|
+
type QueryIsParams<Row extends object> = IsConditions<Row>;
|
|
366
|
+
type QueryWhereinParams<Row extends object> = Partial<Record<keyof Row, unknown[]>>;
|
|
367
|
+
type QueryOrderParams<Row extends object> = [keyof Row & string, {
|
|
368
|
+
ascending?: boolean;
|
|
369
|
+
nullsFirst?: boolean;
|
|
370
|
+
}];
|
|
371
|
+
/**
|
|
372
|
+
* Builder configuration for query construction.
|
|
373
|
+
* Simplified to take Row type directly for better TypeScript performance.
|
|
374
|
+
*
|
|
375
|
+
* @typeParam Row - The row type
|
|
376
|
+
*/
|
|
377
|
+
interface QueryBuilderConfig<Row extends object> {
|
|
378
|
+
table: string;
|
|
379
|
+
conditions: QueryCondition<Row>[];
|
|
380
|
+
order?: QueryOrderParams<Row>;
|
|
381
|
+
mapFn?: (item: Row) => unknown;
|
|
382
|
+
filterFn?: (item: Row) => boolean;
|
|
383
|
+
limit?: number;
|
|
384
|
+
offset?: number;
|
|
385
|
+
softDeleteMode?: SoftDeleteMode;
|
|
386
|
+
softDeleteAppliedByDefault?: boolean;
|
|
387
|
+
/** Database schema to query (defaults to "public") */
|
|
388
|
+
schema?: string;
|
|
389
|
+
}
|
|
390
|
+
//#endregion
|
|
391
|
+
//#region src/query/rpc.d.ts
|
|
392
|
+
/**
|
|
393
|
+
* Options for RPC execution
|
|
394
|
+
*/
|
|
395
|
+
type RpcOptions = {
|
|
396
|
+
/** Database schema to query (defaults to "public") */
|
|
397
|
+
schema?: string;
|
|
398
|
+
/** Count option for the query */
|
|
399
|
+
count?: "exact" | "planned" | "estimated";
|
|
400
|
+
};
|
|
401
|
+
/**
|
|
402
|
+
* Single execution interface for RPC calls
|
|
403
|
+
*/
|
|
404
|
+
type RpcSingleExecution<T> = {
|
|
405
|
+
/**
|
|
406
|
+
* Execute and return Task<Error, Option<T>>
|
|
407
|
+
* Returns None if no result, Some(value) if result exists
|
|
408
|
+
* Call .run() or .runOrThrow() to execute
|
|
409
|
+
*/
|
|
410
|
+
one: () => IOTask<Error, Option$1<T>>;
|
|
411
|
+
/**
|
|
412
|
+
* Execute and return T directly, throwing on error or no result
|
|
413
|
+
*/
|
|
414
|
+
oneOrThrow: () => Promise<T>;
|
|
415
|
+
};
|
|
416
|
+
/**
|
|
417
|
+
* Multi execution interface for RPC calls
|
|
418
|
+
*/
|
|
419
|
+
type RpcMultiExecution<T> = {
|
|
420
|
+
/**
|
|
421
|
+
* Execute and return Task<Error, List<T>>
|
|
422
|
+
* Returns empty List if no results
|
|
423
|
+
* Call .run() or .runOrThrow() to execute
|
|
424
|
+
*/
|
|
425
|
+
many: () => IOTask<Error, List$1<T>>;
|
|
426
|
+
/**
|
|
427
|
+
* Execute and return List<T> directly, throwing on error
|
|
428
|
+
*/
|
|
429
|
+
manyOrThrow: () => Promise<List$1<T>>;
|
|
430
|
+
};
|
|
431
|
+
/**
|
|
432
|
+
* Combined RPC query execution interface
|
|
433
|
+
* Provides both single and multi-result execution methods
|
|
434
|
+
*/
|
|
435
|
+
type RpcExecution<T> = RpcSingleExecution<T> & RpcMultiExecution<T>;
|
|
436
|
+
/**
|
|
437
|
+
* Creates an RPC query for invoking a PostgreSQL function.
|
|
438
|
+
*
|
|
439
|
+
* This function provides type-safe invocation of stored procedures/functions
|
|
440
|
+
* defined in your Supabase database. Return types are inferred from your
|
|
441
|
+
* generated Database types.
|
|
442
|
+
*
|
|
443
|
+
* @template F - The function name (must exist in database schema)
|
|
444
|
+
* @template DB - The database schema type
|
|
445
|
+
* @template S - The schema name (defaults to "public")
|
|
446
|
+
* @param client - The Supabase client instance
|
|
447
|
+
* @param functionName - The name of the PostgreSQL function to call
|
|
448
|
+
* @param args - Arguments to pass to the function (type-safe based on function definition)
|
|
449
|
+
* @param options - Optional configuration (schema, count)
|
|
450
|
+
* @returns An RpcExecution object with one(), oneOrThrow(), many(), manyOrThrow() methods
|
|
451
|
+
*
|
|
452
|
+
* @example
|
|
453
|
+
* ```typescript
|
|
454
|
+
* // Function returning a single object
|
|
455
|
+
* const userStats = await rpc(client, "get_user_stats", { user_id: "123" }).one()
|
|
456
|
+
* if (userStats.isOk()) {
|
|
457
|
+
* const stats = userStats.orThrow()
|
|
458
|
+
* if (stats.isSome()) {
|
|
459
|
+
* console.log(stats.get())
|
|
460
|
+
* }
|
|
461
|
+
* }
|
|
462
|
+
*
|
|
463
|
+
* // Function returning multiple rows
|
|
464
|
+
* const products = await rpc(client, "search_products", { query: "laptop", limit: 10 }).many()
|
|
465
|
+
* products.forEach(p => console.log(p.name))
|
|
466
|
+
*
|
|
467
|
+
* // Using OrThrow variants
|
|
468
|
+
* const stats = await rpc(client, "get_user_stats", { user_id: "123" }).oneOrThrow()
|
|
469
|
+
* const results = await rpc(client, "search_all").manyOrThrow()
|
|
470
|
+
*
|
|
471
|
+
* // Using custom schema
|
|
472
|
+
* const result = await rpc<"cleanup_data", Database, "agent_gate">(client, "cleanup_data").one()
|
|
473
|
+
* ```
|
|
474
|
+
*/
|
|
475
|
+
declare const rpc: <F extends FunctionNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>>(client: SupabaseClientType<DB>, functionName: F, args?: FunctionArgs<F, DB, S>, options?: RpcOptions) => RpcExecution<FunctionReturns<F, DB, S>>;
|
|
476
|
+
//#endregion
|
|
477
|
+
//#region src/query/index.d.ts
|
|
478
|
+
type IsConditionsLocal<T extends object = EmptyObject> = Partial<Record<keyof T, null | boolean>>;
|
|
479
|
+
/**
|
|
480
|
+
* Retrieves a single entity from the specified table.
|
|
481
|
+
* @template T - The table name
|
|
482
|
+
* @template DB - The database schema type
|
|
483
|
+
* @param client - The Supabase client instance
|
|
484
|
+
* @param table - The table to query
|
|
485
|
+
* @param where - Conditions to filter by
|
|
486
|
+
* @param is - IS conditions to filter by
|
|
487
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
488
|
+
* @returns A Task resolving to the entity if found
|
|
489
|
+
*/
|
|
490
|
+
declare const getEntity: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, schema?: string) => IOTask<Error, TableRow<T, DB>>;
|
|
491
|
+
/**
|
|
492
|
+
* Retrieves multiple entities from the specified table.
|
|
493
|
+
* @template T - The table name
|
|
494
|
+
* @template DB - The database schema type
|
|
495
|
+
* @param client - The Supabase client instance
|
|
496
|
+
* @param table - The table to query
|
|
497
|
+
* @param where - Conditions to filter by
|
|
498
|
+
* @param is - IS conditions to filter by
|
|
499
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
500
|
+
* @param order - Optional ordering parameters
|
|
501
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
502
|
+
* @returns A Task resolving to the entities if found
|
|
503
|
+
*/
|
|
504
|
+
declare const getEntities: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where?: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, order?: [keyof TableRow<T, DB> & string, {
|
|
505
|
+
ascending?: boolean;
|
|
506
|
+
nullsFirst?: boolean;
|
|
507
|
+
}], schema?: string) => IOTask<Error, List$1<TableRow<T, DB>>>;
|
|
508
|
+
/**
|
|
509
|
+
* Adds multiple entities to the specified table.
|
|
510
|
+
* @template T - The table name
|
|
511
|
+
* @template DB - The database schema type
|
|
512
|
+
* @param client - The Supabase client instance
|
|
513
|
+
* @param table - The table to insert into
|
|
514
|
+
* @param entities - The entities to add
|
|
515
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
516
|
+
* @returns A Task resolving to the added entities
|
|
517
|
+
*/
|
|
518
|
+
declare const addEntities: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, entities: TableInsert<T, DB>[], schema?: string) => IOTask<Error, List$1<TableRow<T, DB>>>;
|
|
519
|
+
/**
|
|
520
|
+
* Updates a single entity in the specified table.
|
|
521
|
+
* @template T - The table name
|
|
522
|
+
* @template DB - The database schema type
|
|
523
|
+
* @param client - The Supabase client instance
|
|
524
|
+
* @param table - The table to update
|
|
525
|
+
* @param entities - The entity data to update
|
|
526
|
+
* @param where - Conditions to filter by
|
|
527
|
+
* @param is - IS conditions to filter by
|
|
528
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
529
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
530
|
+
* @returns A Task resolving to the updated entity
|
|
531
|
+
*/
|
|
532
|
+
declare const updateEntity: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, entities: TableUpdate<T, DB>, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, TableRow<T, DB>>;
|
|
533
|
+
/**
|
|
534
|
+
* Upserts multiple entities in the specified table (insert or update on conflict).
|
|
535
|
+
* Uses Supabase's upsert() under the hood with onConflict resolution.
|
|
536
|
+
* @template T - The table name
|
|
537
|
+
* @template DB - The database schema type
|
|
538
|
+
* @param client - The Supabase client instance
|
|
539
|
+
* @param table - The table to upsert into
|
|
540
|
+
* @param entities - The entities to upsert
|
|
541
|
+
* @param identity - The column(s) to use for conflict resolution (default: "id")
|
|
542
|
+
* @param where - Additional conditions to filter by
|
|
543
|
+
* @param is - IS conditions to filter by
|
|
544
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
545
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
546
|
+
* @returns A Task resolving to the upserted entities
|
|
547
|
+
*/
|
|
548
|
+
declare const upsertEntities: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, entities: TableUpdate<T, DB>[], identity?: (keyof TableRow<T, DB> & string) | (keyof TableRow<T, DB> & string)[], where?: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, List$1<TableRow<T, DB>>>;
|
|
549
|
+
/**
|
|
550
|
+
* Deletes a single entity from the specified table.
|
|
551
|
+
* @template T - The table name
|
|
552
|
+
* @template DB - The database schema type
|
|
553
|
+
* @param client - The Supabase client instance
|
|
554
|
+
* @param table - The table to delete from
|
|
555
|
+
* @param where - Conditions to filter by
|
|
556
|
+
* @param is - IS conditions to filter by
|
|
557
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
558
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
559
|
+
* @returns A Task resolving to the deleted entity
|
|
560
|
+
*/
|
|
561
|
+
declare const deleteEntity: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, TableRow<T, DB>>;
|
|
562
|
+
/**
|
|
563
|
+
* Deletes multiple entities from the specified table.
|
|
564
|
+
* @template T - The table name
|
|
565
|
+
* @template DB - The database schema type
|
|
566
|
+
* @param client - The Supabase client instance
|
|
567
|
+
* @param table - The table to delete from
|
|
568
|
+
* @param where - Conditions to filter by
|
|
569
|
+
* @param is - IS conditions to filter by
|
|
570
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
571
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
572
|
+
* @returns A Task resolving to the deleted entities
|
|
573
|
+
*/
|
|
574
|
+
declare const deleteEntities: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, List$1<TableRow<T, DB>>>;
|
|
575
|
+
/**
|
|
576
|
+
* Soft deletes a single entity by setting the deleted timestamp.
|
|
577
|
+
* @template T - The table name
|
|
578
|
+
* @template DB - The database schema type
|
|
579
|
+
* @param client - The Supabase client instance
|
|
580
|
+
* @param table - The table to soft delete from
|
|
581
|
+
* @param where - Conditions to filter by
|
|
582
|
+
* @param is - IS conditions to filter by
|
|
583
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
584
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
585
|
+
* @returns A Task resolving to the soft deleted entity
|
|
586
|
+
*/
|
|
587
|
+
declare const softDeleteEntity: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, TableRow<T, DB>>;
|
|
588
|
+
/**
|
|
589
|
+
* Soft deletes multiple entities by setting the deleted timestamp.
|
|
590
|
+
* @template T - The table name
|
|
591
|
+
* @template DB - The database schema type
|
|
592
|
+
* @param client - The Supabase client instance
|
|
593
|
+
* @param table - The table to soft delete from
|
|
594
|
+
* @param where - Conditions to filter by
|
|
595
|
+
* @param is - IS conditions to filter by
|
|
596
|
+
* @param wherein - WHERE IN conditions to filter by
|
|
597
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
598
|
+
* @returns A Task resolving to the soft deleted entities
|
|
599
|
+
*/
|
|
600
|
+
declare const softDeleteEntities: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where: EntityWhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, schema?: string) => IOTask<Error, List$1<TableRow<T, DB>>>;
|
|
601
|
+
/**
|
|
602
|
+
* Creates a new Query for the specified table with initial conditions.
|
|
603
|
+
* This is the new Query-based API that supports OR chaining and functional operations.
|
|
604
|
+
*
|
|
605
|
+
* @template T - The table name
|
|
606
|
+
* @template DB - The database schema type
|
|
607
|
+
* @param client - The Supabase client instance
|
|
608
|
+
* @param table - The table to query
|
|
609
|
+
* @param where - Initial WHERE conditions to filter by
|
|
610
|
+
* @param is - Initial IS conditions to filter by
|
|
611
|
+
* @param wherein - Initial WHERE IN conditions to filter by
|
|
612
|
+
* @param order - Optional ordering parameters
|
|
613
|
+
* @param schema - Database schema to query (defaults to "public")
|
|
614
|
+
* @returns A Query instance that supports chaining and lazy evaluation
|
|
615
|
+
*
|
|
616
|
+
* @example
|
|
617
|
+
* // Simple query
|
|
618
|
+
* const user = await query(client, "users", { id: "123" }).one()
|
|
619
|
+
*
|
|
620
|
+
* @example
|
|
621
|
+
* // Query with OR logic
|
|
622
|
+
* const users = await query(client, "users", { role: "admin" })
|
|
623
|
+
* .or({ role: "moderator" })
|
|
624
|
+
* .many()
|
|
625
|
+
*
|
|
626
|
+
* @example
|
|
627
|
+
* // Query with functional operations
|
|
628
|
+
* const names = await query(client, "users", { active: true })
|
|
629
|
+
* .map(user => user.name)
|
|
630
|
+
* .filter(name => name.startsWith('A'))
|
|
631
|
+
* .many()
|
|
632
|
+
*
|
|
633
|
+
* @example
|
|
634
|
+
* // Query with custom schema
|
|
635
|
+
* const items = await query(client, "items", { active: true }, undefined, undefined, undefined, "inventory").many()
|
|
636
|
+
*/
|
|
637
|
+
declare const query: <T extends TableNames<DB>, DB extends DatabaseSchema = Database>(client: SupabaseClientType<DB>, table: T, where?: WhereConditions<TableRow<T, DB>>, is?: IsConditionsLocal<TableRow<T, DB>>, wherein?: Partial<Record<keyof TableRow<T, DB>, unknown[]>>, order?: [keyof TableRow<T, DB> & string, {
|
|
638
|
+
ascending?: boolean;
|
|
639
|
+
nullsFirst?: boolean;
|
|
640
|
+
}], schema?: string) => Query<TableRow<T, DB>>;
|
|
641
|
+
//#endregion
|
|
642
|
+
//#region src/entity/types.d.ts
|
|
643
|
+
/**
|
|
644
|
+
* Partition key can be a string or any branded string type
|
|
645
|
+
* This enables type-safe partition keys using functype's Brand/ValidatedBrand
|
|
646
|
+
*/
|
|
647
|
+
type PartitionKey = string | Brand<string, string>;
|
|
648
|
+
/**
|
|
649
|
+
* Field-level type safety for queries
|
|
650
|
+
*/
|
|
651
|
+
type TypedRecord<T, V> = Partial<Record<keyof T, V>>;
|
|
652
|
+
/**
|
|
653
|
+
* Configuration for standard Entity (no partition)
|
|
654
|
+
*/
|
|
655
|
+
type EntityConfig = {
|
|
656
|
+
/** Soft delete filtering. true = exclude deleted items, false = include deleted items */
|
|
657
|
+
softDelete: boolean;
|
|
658
|
+
/** Database schema to query (defaults to "public") */
|
|
659
|
+
schema?: string;
|
|
660
|
+
};
|
|
661
|
+
/**
|
|
662
|
+
* Configuration for PartitionedEntity
|
|
663
|
+
*/
|
|
664
|
+
type PartitionedEntityConfig = {
|
|
665
|
+
/** The database column name used for partitioning (e.g., "tenant_id") */
|
|
666
|
+
partitionField: string;
|
|
667
|
+
/** Soft delete filtering. true = exclude deleted items, false = include deleted items */
|
|
668
|
+
softDelete: boolean;
|
|
669
|
+
/** Database schema to query (defaults to "public") */
|
|
670
|
+
schema?: string;
|
|
671
|
+
};
|
|
672
|
+
type WhereParams<T extends object = EmptyObject> = {
|
|
673
|
+
where?: EntityWhereConditions<T>;
|
|
674
|
+
};
|
|
675
|
+
type IsParams<T extends object = EmptyObject> = {
|
|
676
|
+
is?: TypedRecord<T, null | boolean>;
|
|
677
|
+
};
|
|
678
|
+
type WhereinParams<T extends object = EmptyObject> = {
|
|
679
|
+
wherein?: TypedRecord<T, unknown[]>;
|
|
680
|
+
};
|
|
681
|
+
type OrderParams<T extends object = EmptyObject> = {
|
|
682
|
+
order?: [keyof T & string, {
|
|
683
|
+
ascending?: boolean;
|
|
684
|
+
nullsFirst?: boolean;
|
|
685
|
+
}];
|
|
686
|
+
};
|
|
687
|
+
type ComparisonParams<T extends object = EmptyObject> = {
|
|
688
|
+
gte?: TypedRecord<T, number | string | Date>;
|
|
689
|
+
gt?: TypedRecord<T, number | string | Date>;
|
|
690
|
+
lte?: TypedRecord<T, number | string | Date>;
|
|
691
|
+
lt?: TypedRecord<T, number | string | Date>;
|
|
692
|
+
neq?: TypedRecord<T, unknown>;
|
|
693
|
+
like?: TypedRecord<T, string>;
|
|
694
|
+
ilike?: TypedRecord<T, string>;
|
|
695
|
+
};
|
|
696
|
+
type NotParams<T extends object = EmptyObject> = {
|
|
697
|
+
not?: {
|
|
698
|
+
is?: TypedRecord<T, null | boolean>;
|
|
699
|
+
in?: TypedRecord<T, unknown[]>;
|
|
700
|
+
};
|
|
701
|
+
};
|
|
702
|
+
type IdParam = {
|
|
703
|
+
id: string;
|
|
704
|
+
};
|
|
705
|
+
type GetItemParams<T extends object = EmptyObject> = IdParam & WhereParams<T> & IsParams<T>;
|
|
706
|
+
type GetItemsParams<T extends object = EmptyObject> = WhereParams<T> & IsParams<T> & WhereinParams<T> & OrderParams<T> & ComparisonParams<T> & NotParams<T>;
|
|
707
|
+
type AddItemsParams<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
708
|
+
items: TableInsert<T, DB, S>[];
|
|
709
|
+
};
|
|
710
|
+
/**
|
|
711
|
+
* Prisma-style update params for single item: { where, data }
|
|
712
|
+
*/
|
|
713
|
+
type UpdateItemParams<T extends TableNames<DB, S>, Row extends object = EmptyObject, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
714
|
+
/** Conditions to match the item to update */
|
|
715
|
+
where: EntityWhereConditions<Row>;
|
|
716
|
+
/** The data to update */
|
|
717
|
+
data: TableUpdate<T, DB, S>;
|
|
718
|
+
} & IsParams<Row> & WhereinParams<Row>;
|
|
719
|
+
/**
|
|
720
|
+
* Prisma-style update params for multiple items: { where, data }
|
|
721
|
+
*/
|
|
722
|
+
type UpdateItemsParams<T extends TableNames<DB, S>, Row extends object = EmptyObject, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
723
|
+
/** Conditions to match items to update */
|
|
724
|
+
where: EntityWhereConditions<Row>;
|
|
725
|
+
/** The data to update on all matched items */
|
|
726
|
+
data: TableUpdate<T, DB, S>;
|
|
727
|
+
} & IsParams<Row> & WhereinParams<Row>;
|
|
728
|
+
/**
|
|
729
|
+
* Batch upsert params: update multiple rows with different data per row
|
|
730
|
+
*/
|
|
731
|
+
type UpsertItemsParams<T extends TableNames<DB, S>, Row extends object = EmptyObject, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
732
|
+
/** Array of items to upsert, each with its own data */
|
|
733
|
+
items: TableUpdate<T, DB, S>[];
|
|
734
|
+
/** Column(s) to use as identity for matching (default: "id") */
|
|
735
|
+
identity?: (keyof Row & string) | (keyof Row & string)[];
|
|
736
|
+
};
|
|
737
|
+
/**
|
|
738
|
+
* Delete params for single item: { where }
|
|
739
|
+
*/
|
|
740
|
+
type DeleteItemParams<Row extends object = EmptyObject> = {
|
|
741
|
+
/** Conditions to match the item to delete */
|
|
742
|
+
where: EntityWhereConditions<Row>;
|
|
743
|
+
} & IsParams<Row> & WhereinParams<Row>;
|
|
744
|
+
/**
|
|
745
|
+
* Delete params for multiple items: { where }
|
|
746
|
+
*/
|
|
747
|
+
type DeleteItemsParams<Row extends object = EmptyObject> = {
|
|
748
|
+
/** Conditions to match items to delete */
|
|
749
|
+
where: EntityWhereConditions<Row>;
|
|
750
|
+
} & IsParams<Row> & WhereinParams<Row>;
|
|
751
|
+
/**
|
|
752
|
+
* Wrapper type for multi-result mutation operations that implements standard execution interface
|
|
753
|
+
*/
|
|
754
|
+
type MutationMultiExecution<T> = MultiExecution<T>;
|
|
755
|
+
/**
|
|
756
|
+
* Wrapper type for single-result mutation operations that implements standard execution interface
|
|
757
|
+
*/
|
|
758
|
+
type MutationSingleExecution<T> = SingleExecution<T>;
|
|
759
|
+
/**
|
|
760
|
+
* Creates a multi-result mutation query that implements the standard execution interface
|
|
761
|
+
*/
|
|
762
|
+
declare function MultiMutationQuery<T>(task: IOTask<Error, List$1<T>>): MutationMultiExecution<T>;
|
|
763
|
+
/**
|
|
764
|
+
* Creates a single-result mutation query that implements the standard execution interface
|
|
765
|
+
*/
|
|
766
|
+
declare function SingleMutationQuery<T>(task: IOTask<Error, T>): MutationSingleExecution<T>;
|
|
767
|
+
/**
|
|
768
|
+
* Base interface for Entity instances (global, no partition)
|
|
769
|
+
*
|
|
770
|
+
* @typeParam T - The table name
|
|
771
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
772
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
773
|
+
*/
|
|
774
|
+
type IEntity<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
775
|
+
getItem(params: GetItemParams<TableRow<T, DB, S>>): Query<TableRow<T, DB, S>>;
|
|
776
|
+
getItems(params?: GetItemsParams<TableRow<T, DB, S>>): Query<TableRow<T, DB, S>>;
|
|
777
|
+
addItems(params: AddItemsParams<T, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
778
|
+
updateItem(params: UpdateItemParams<T, TableRow<T, DB, S>, DB, S>): MutationSingleExecution<TableRow<T, DB, S>>;
|
|
779
|
+
updateItems(params: UpdateItemsParams<T, TableRow<T, DB, S>, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
780
|
+
upsertItems(params: UpsertItemsParams<T, TableRow<T, DB, S>, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
781
|
+
deleteItem(params: DeleteItemParams<TableRow<T, DB, S>>): MutationSingleExecution<TableRow<T, DB, S>>;
|
|
782
|
+
deleteItems(params: DeleteItemsParams<TableRow<T, DB, S>>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
783
|
+
};
|
|
784
|
+
/**
|
|
785
|
+
* Interface for PartitionedEntity instances (requires partition key on calls)
|
|
786
|
+
*
|
|
787
|
+
* @typeParam T - The table name
|
|
788
|
+
* @typeParam K - The partition key type
|
|
789
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
790
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
791
|
+
*/
|
|
792
|
+
type IPartitionedEntity<T extends TableNames<DB, S>, K$1 extends PartitionKey, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
793
|
+
getItem(partitionKey: K$1, params: GetItemParams<TableRow<T, DB, S>>): Query<TableRow<T, DB, S>>;
|
|
794
|
+
getItems(partitionKey: K$1, params?: GetItemsParams<TableRow<T, DB, S>>): Query<TableRow<T, DB, S>>;
|
|
795
|
+
addItems(params: AddItemsParams<T, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
796
|
+
updateItem(partitionKey: K$1, params: UpdateItemParams<T, TableRow<T, DB, S>, DB, S>): MutationSingleExecution<TableRow<T, DB, S>>;
|
|
797
|
+
updateItems(partitionKey: K$1, params: UpdateItemsParams<T, TableRow<T, DB, S>, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
798
|
+
upsertItems(partitionKey: K$1, params: UpsertItemsParams<T, TableRow<T, DB, S>, DB, S>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
799
|
+
deleteItem(partitionKey: K$1, params: DeleteItemParams<TableRow<T, DB, S>>): MutationSingleExecution<TableRow<T, DB, S>>;
|
|
800
|
+
deleteItems(partitionKey: K$1, params: DeleteItemsParams<TableRow<T, DB, S>>): MutationMultiExecution<TableRow<T, DB, S>>;
|
|
801
|
+
};
|
|
802
|
+
/**
|
|
803
|
+
* Type for an entity instance for a specific table
|
|
804
|
+
* @deprecated Use IEntity<T, DB, S> instead
|
|
805
|
+
*/
|
|
806
|
+
type EntityType<T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = IEntity<T, DB, S>;
|
|
807
|
+
/**
|
|
808
|
+
* Configuration for ViewEntity (read-only, no partition)
|
|
809
|
+
*/
|
|
810
|
+
type ViewEntityConfig = {
|
|
811
|
+
/** Database schema to query (defaults to "public") */
|
|
812
|
+
schema?: string;
|
|
813
|
+
};
|
|
814
|
+
/**
|
|
815
|
+
* Configuration for PartitionedViewEntity
|
|
816
|
+
*/
|
|
817
|
+
type PartitionedViewEntityConfig = {
|
|
818
|
+
/** The database column name used for partitioning (e.g., "tenant_id") */
|
|
819
|
+
partitionField: string;
|
|
820
|
+
/** Database schema to query (defaults to "public") */
|
|
821
|
+
schema?: string;
|
|
822
|
+
};
|
|
823
|
+
/**
|
|
824
|
+
* Read-only interface for ViewEntity instances (global, no partition)
|
|
825
|
+
* Views only have Row type, so only read operations are available.
|
|
826
|
+
*
|
|
827
|
+
* @typeParam V - The view name
|
|
828
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
829
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
830
|
+
*/
|
|
831
|
+
type IViewEntity<V extends ViewNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
832
|
+
getItem(params: GetItemParams<ViewRow<V, DB, S>>): Query<ViewRow<V, DB, S>>;
|
|
833
|
+
getItems(params?: GetItemsParams<ViewRow<V, DB, S>>): Query<ViewRow<V, DB, S>>;
|
|
834
|
+
};
|
|
835
|
+
/**
|
|
836
|
+
* Read-only interface for PartitionedViewEntity instances (requires partition key on calls)
|
|
837
|
+
* Views only have Row type, so only read operations are available.
|
|
838
|
+
*
|
|
839
|
+
* @typeParam V - The view name
|
|
840
|
+
* @typeParam K - The partition key type
|
|
841
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
842
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
843
|
+
*/
|
|
844
|
+
type IPartitionedViewEntity<V extends ViewNames<DB, S>, K$1 extends PartitionKey, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>> = {
|
|
845
|
+
getItem(partitionKey: K$1, params: GetItemParams<ViewRow<V, DB, S>>): Query<ViewRow<V, DB, S>>;
|
|
846
|
+
getItems(partitionKey: K$1, params?: GetItemsParams<ViewRow<V, DB, S>>): Query<ViewRow<V, DB, S>>;
|
|
847
|
+
};
|
|
848
|
+
//#endregion
|
|
849
|
+
//#region src/entity/Entity.d.ts
|
|
850
|
+
/**
|
|
851
|
+
* Creates an entity interface with methods for interacting with the given table.
|
|
852
|
+
*
|
|
853
|
+
* @param client The Supabase client instance to use for queries.
|
|
854
|
+
* @param name The name of the table to interact with.
|
|
855
|
+
* @param config Configuration for entity behavior.
|
|
856
|
+
* @returns An object with methods for interacting with the table.
|
|
857
|
+
*
|
|
858
|
+
* @typeParam T - The table name type
|
|
859
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
860
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
861
|
+
*
|
|
862
|
+
* @example
|
|
863
|
+
* ```typescript
|
|
864
|
+
* // Using default public schema
|
|
865
|
+
* const Users = Entity<"users">(client, "users", { softDelete: false })
|
|
866
|
+
*
|
|
867
|
+
* // Using a custom schema
|
|
868
|
+
* const Tokens = Entity<"provider_tokens", Database, "agent_todo">(
|
|
869
|
+
* client, "provider_tokens", { softDelete: false }
|
|
870
|
+
* )
|
|
871
|
+
* ```
|
|
872
|
+
*/
|
|
873
|
+
declare const Entity: <T extends TableNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>>(client: SupabaseClientType<DB>, name: T, config: EntityConfig) => IEntity<T, DB, S>;
|
|
874
|
+
//#endregion
|
|
875
|
+
//#region src/entity/PartitionedEntity.d.ts
|
|
876
|
+
/**
|
|
877
|
+
* Creates a partitioned entity interface where all queries require a partition key.
|
|
878
|
+
*
|
|
879
|
+
* @param client The Supabase client instance to use for queries.
|
|
880
|
+
* @param name The name of the table to interact with.
|
|
881
|
+
* @param config Configuration including partition field and soft delete behavior.
|
|
882
|
+
* @returns An object with methods for interacting with the partitioned table.
|
|
883
|
+
*
|
|
884
|
+
* @typeParam T - The table name type
|
|
885
|
+
* @typeParam K - The partition key type (string or branded type)
|
|
886
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
887
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
888
|
+
*
|
|
889
|
+
* @example
|
|
890
|
+
* ```typescript
|
|
891
|
+
* // Using default public schema
|
|
892
|
+
* const UserEntity = PartitionedEntity<"users", TenantId>(client, "users", {
|
|
893
|
+
* partitionField: "tenant_id",
|
|
894
|
+
* softDelete: true
|
|
895
|
+
* })
|
|
896
|
+
*
|
|
897
|
+
* // Using a custom schema
|
|
898
|
+
* const TaskEntity = PartitionedEntity<"tasks", TenantId, Database, "agent_todo">(
|
|
899
|
+
* client, "tasks", { partitionField: "user_id", softDelete: false }
|
|
900
|
+
* )
|
|
901
|
+
* ```
|
|
902
|
+
*/
|
|
903
|
+
declare const PartitionedEntity: <T extends TableNames<DB, S>, K$1 extends PartitionKey = string, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>>(client: SupabaseClientType<DB>, name: T, config: PartitionedEntityConfig) => IPartitionedEntity<T, K$1, DB, S>;
|
|
904
|
+
//#endregion
|
|
905
|
+
//#region src/entity/ViewEntity.d.ts
|
|
906
|
+
/**
|
|
907
|
+
* Creates a read-only entity interface for querying database views.
|
|
908
|
+
*
|
|
909
|
+
* @param client The Supabase client instance to use for queries.
|
|
910
|
+
* @param name The name of the view to query.
|
|
911
|
+
* @param config Optional configuration for the view entity.
|
|
912
|
+
* @returns An object with read-only methods for querying the view.
|
|
913
|
+
*
|
|
914
|
+
* @typeParam V - The view name type
|
|
915
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
916
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
917
|
+
*
|
|
918
|
+
* @example
|
|
919
|
+
* ```typescript
|
|
920
|
+
* // Using default public schema
|
|
921
|
+
* const ActiveUsersView = ViewEntity<"active_users_view">(client, "active_users_view")
|
|
922
|
+
*
|
|
923
|
+
* // Using a custom schema
|
|
924
|
+
* const AuthUsersView = ViewEntity<"auth_users_view", Database, "agent_gate">(
|
|
925
|
+
* client, "auth_users_view", { schema: "agent_gate" }
|
|
926
|
+
* )
|
|
927
|
+
* ```
|
|
928
|
+
*/
|
|
929
|
+
declare const ViewEntity: <V extends ViewNames<DB, S>, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>>(client: SupabaseClientType<DB>, name: V, config?: ViewEntityConfig) => IViewEntity<V, DB, S>;
|
|
930
|
+
//#endregion
|
|
931
|
+
//#region src/entity/PartitionedViewEntity.d.ts
|
|
932
|
+
/**
|
|
933
|
+
* Creates a read-only partitioned entity interface for querying database views.
|
|
934
|
+
*
|
|
935
|
+
* @param client The Supabase client instance to use for queries.
|
|
936
|
+
* @param name The name of the view to query.
|
|
937
|
+
* @param config Configuration including partition field.
|
|
938
|
+
* @returns An object with read-only methods for querying the partitioned view.
|
|
939
|
+
*
|
|
940
|
+
* @typeParam V - The view name type
|
|
941
|
+
* @typeParam K - The partition key type (string or branded type)
|
|
942
|
+
* @typeParam DB - The database schema type (defaults to placeholder Database)
|
|
943
|
+
* @typeParam S - The schema name (defaults to "public")
|
|
944
|
+
*
|
|
945
|
+
* @example
|
|
946
|
+
* ```typescript
|
|
947
|
+
* // Using default public schema
|
|
948
|
+
* const TenantStatsView = PartitionedViewEntity<"tenant_stats_view", TenantId>(
|
|
949
|
+
* client, "tenant_stats_view", { partitionField: "tenant_id" }
|
|
950
|
+
* )
|
|
951
|
+
*
|
|
952
|
+
* // Using a custom schema
|
|
953
|
+
* const UserActivityView = PartitionedViewEntity<"user_activity_view", UserId, Database, "analytics">(
|
|
954
|
+
* client, "user_activity_view", { partitionField: "user_id", schema: "analytics" }
|
|
955
|
+
* )
|
|
956
|
+
* ```
|
|
957
|
+
*/
|
|
958
|
+
declare const PartitionedViewEntity: <V extends ViewNames<DB, S>, K$1 extends PartitionKey = string, DB extends DatabaseSchema = Database, S extends SchemaNames<DB> = "public" & SchemaNames<DB>>(client: SupabaseClientType<DB>, name: V, config: PartitionedViewEntityConfig) => IPartitionedViewEntity<V, K$1, DB, S>;
|
|
959
|
+
//#endregion
|
|
960
|
+
//#region src/utils/errors.d.ts
|
|
961
|
+
/**
|
|
962
|
+
* Supabase/Postgrest error structure
|
|
963
|
+
*/
|
|
964
|
+
type SupabaseErrorObject = {
|
|
965
|
+
message: string;
|
|
966
|
+
code?: string;
|
|
967
|
+
details?: string;
|
|
968
|
+
hint?: string;
|
|
969
|
+
};
|
|
970
|
+
/**
|
|
971
|
+
* Custom Error class that preserves Supabase error details
|
|
972
|
+
*/
|
|
973
|
+
declare class SupabaseError extends Error {
|
|
974
|
+
readonly code?: string;
|
|
975
|
+
readonly details?: string;
|
|
976
|
+
readonly hint?: string;
|
|
977
|
+
constructor(error: SupabaseErrorObject | unknown);
|
|
978
|
+
/**
|
|
979
|
+
* Override toString to include all error details
|
|
980
|
+
*/
|
|
981
|
+
toString(): string;
|
|
982
|
+
}
|
|
983
|
+
/**
|
|
984
|
+
* Convert any error to a proper Error instance
|
|
985
|
+
*/
|
|
986
|
+
declare const toError: (error: unknown) => Error;
|
|
987
|
+
//#endregion
|
|
988
|
+
export { type AddItemsParams, type ComparisonOperators, type Database, type DatabaseSchema, type DeleteItemParams, type DeleteItemsParams, type EmptyObject, Entity, type EntityConfig, type EntityQuery, type EntityType, type EntityWhereConditions, type ExecutableQuery, type FunctionArgs, type FunctionNames, type FunctionReturns, type GetItemParams, type GetItemsParams, type IEntity, IO, type IPartitionedEntity, type IPartitionedViewEntity, type IViewEntity, type IdParam, type IsConditions, type IsParams, List, type MappedQuery, type MultiExecution, MultiMutationQuery, type MutationMultiExecution, type MutationSingleExecution, Option, type OrderParams, type PartitionKey, PartitionedEntity, type PartitionedEntityConfig, PartitionedViewEntity, type PartitionedViewEntityConfig, type Query, type QueryBuilder, type QueryBuilderConfig, type QueryCondition, type QueryIsParams, type QueryOrderParams, type QueryWhereParams, type QueryWhereinParams, type RpcExecution, type RpcMultiExecution, type RpcOptions, type RpcQueryBuilder, type RpcSingleExecution, type SchemaNames, type SingleExecution, SingleMutationQuery, type SoftDeleteMode, type SupabaseClientType, SupabaseError, type SupabaseErrorObject, type TableInsert, type TableNames, type TableRow, type TableUpdate, type Task, type TypedDatabase, type TypedRecord, type UpdateItemParams, type UpdateItemsParams, type UpsertItemsParams, type ValidSchema, ViewEntity, type ViewEntityConfig, type ViewNames, type ViewRow, type WhereConditions, type WhereParams, type WhereinParams, addEntities, deleteEntities, deleteEntity, getEntities, getEntity, isMappedQuery, isQuery, query, rpc, softDeleteEntities, softDeleteEntity, toError, updateEntity, upsertEntities };
|
|
989
|
+
//# sourceMappingURL=index.d.ts.map
|