The best way to control Claude Code, Codex and more from any computer or phone

main
ts 274 lines 7.9 KB
Raw
1 /**
2 * Typed object-store descriptors for the browser IndexedDB integration.
3 *
4 * An {@link IndexedDbTable} is the schema-backed description of one IndexedDB
5 * object store. It carries the store name, row schema, key path, index key
6 * paths, auto-increment mode, and transaction durability used by database
7 * versions, migrations, and typed queries. The `make` constructor also derives
8 * the read, array, and auto-increment write schemas used by the query builder.
9 *
10 * @see {@link make} for constructing table descriptors.
11 *
12 * @stability unstable
13 * @since 4.0.0
14 */
15 import { type Pipeable, pipeArguments } from "effect/Pipeable"
16 import * as Schema from "effect/Schema"
17 import * as Struct from "effect/Struct"
18 import type { NoInfer } from "effect/Types"
19 import * as IndexedDb from "./IndexedDb.ts"
20 import type * as IndexedDbQueryBuilder from "./IndexedDbQueryBuilder.ts"
21
22 const TypeId = "~@effect/platform-browser/IndexedDbTable"
23
24 /**
25 * Typed IndexedDB table definition containing its name, schema, key path, indexes, auto-increment setting, and transaction durability.
26 *
27 * @stability unstable
28 * @category models
29 * @since 4.0.0
30 */
31 export interface IndexedDbTable<
32 out Name extends string,
33 out TableSchema extends AnySchemaStruct,
34 out Indexes extends Record<
35 string,
36 IndexedDbQueryBuilder.KeyPath<TableSchema>
37 >,
38 out KeyPath extends Readonly<IDBValidKey | undefined>,
39 out AutoIncrement extends boolean
40 > extends Pipeable {
41 new(_: never): {}
42 readonly [TypeId]: typeof TypeId
43 readonly tableName: Name
44 readonly tableSchema: TableSchema
45 readonly readSchema: Schema.Top
46 readonly autoincrementSchema: Schema.Top
47 readonly arraySchema: Schema.Top
48 readonly keyPath: KeyPath
49 readonly indexes: Indexes
50 readonly autoIncrement: AutoIncrement
51 readonly durability: IDBTransactionDurability
52 }
53
54 /**
55 * Schema constraint for table schemas that expose struct fields.
56 *
57 * @stability unstable
58 * @category models
59 * @since 4.0.0
60 */
61 export type AnySchemaStruct = Schema.Top & {
62 readonly fields: Schema.Struct.Fields
63 }
64
65 /**
66 * Type-erased shape of an `IndexedDbTable` used when table type parameters are not needed.
67 *
68 * @stability unstable
69 * @category models
70 * @since 4.0.0
71 */
72 export interface Any {
73 readonly [TypeId]: typeof TypeId
74 readonly keyPath: any
75 readonly tableName: string
76 readonly tableSchema: Schema.Top
77 readonly readSchema: Schema.Top
78 readonly autoincrementSchema: Schema.Top
79 readonly arraySchema: Schema.Top
80 readonly autoIncrement: boolean
81 readonly indexes: any
82 }
83
84 /**
85 * Type-erased `IndexedDbTable` retaining the table interface properties with broad type parameters.
86 *
87 * @stability unstable
88 * @category models
89 * @since 4.0.0
90 */
91 export type AnyWithProps = IndexedDbTable<
92 string,
93 AnySchemaStruct,
94 any,
95 any,
96 boolean
97 >
98
99 /**
100 * Extracts the table name type from an `IndexedDbTable`.
101 *
102 * @stability unstable
103 * @category utility types
104 * @since 4.0.0
105 */
106 export type TableName<Table extends Any> = Table["tableName"]
107 /**
108 * Extracts the key-path type from an `IndexedDbTable`.
109 *
110 * @stability unstable
111 * @category utility types
112 * @since 4.0.0
113 */
114 export type KeyPath<Table extends Any> = Table["keyPath"]
115
116 /**
117 * Extracts the auto-increment flag type from an `IndexedDbTable`.
118 *
119 * @stability unstable
120 * @category utility types
121 * @since 4.0.0
122 */
123 export type AutoIncrement<Table extends Any> = Table["autoIncrement"]
124
125 /**
126 * Extracts the schema type from an `IndexedDbTable`.
127 *
128 * @stability unstable
129 * @category utility types
130 * @since 4.0.0
131 */
132 export type TableSchema<Table extends Any> = Table["tableSchema"]
133 /**
134 * Extracts the decoding or encoding service requirements needed by an `IndexedDbTable` schema.
135 *
136 * @stability unstable
137 * @category utility types
138 * @since 4.0.0
139 */
140 export type Context<Table extends Any> =
141 | Table["tableSchema"]["DecodingServices"]
142 | Table["tableSchema"]["EncodingServices"]
143
144 /**
145 * Extracts the encoded row type from an `IndexedDbTable` schema.
146 *
147 * @stability unstable
148 * @category utility types
149 * @since 4.0.0
150 */
151 export type Encoded<Table extends Any> = Table["tableSchema"]["Encoded"]
152
153 /**
154 * Extracts the index definition map from an `IndexedDbTable`.
155 *
156 * @stability unstable
157 * @category utility types
158 * @since 4.0.0
159 */
160 export type Indexes<Table extends Any> = Table["indexes"]
161
162 /**
163 * Selects the table with the given name from a union of `IndexedDbTable` types.
164 *
165 * @stability unstable
166 * @category utility types
167 * @since 4.0.0
168 */
169 export type WithName<Table extends Any, TableName extends string> = Extract<
170 Table,
171 { readonly tableName: TableName }
172 >
173
174 const Proto = {
175 [TypeId]: TypeId,
176 pipe() {
177 return pipeArguments(this, arguments)
178 }
179 }
180
181 /**
182 * Creates a typed IndexedDB table definition from its name, schema, optional key path, indexes, auto-increment flag, and durability.
183 *
184 * **When to use**
185 *
186 * Use to define a typed object-store descriptor for inclusion in an
187 * `IndexedDbVersion` and for migration or query APIs.
188 *
189 * **Details**
190 *
191 * `autoIncrement` defaults to `false` and `durability` defaults to `"relaxed"`.
192 * Tables without a key path get a read schema that includes an out-of-line
193 * `key`, while auto-increment tables use a write schema where the generated key
194 * may be omitted.
195 *
196 * **Gotchas**
197 *
198 * Tables without a key path cannot define a `key` field in their row schema.
199 * Key paths and index paths must point to encoded fields whose values are valid
200 * IndexedDB keys, and declared indexes still need to be created during
201 * database migrations.
202 *
203 * @see `IndexedDbVersion.make` for grouping table definitions into a schema version
204 *
205 * @stability unstable
206 * @category constructors
207 * @since 4.0.0
208 */
209 export const make = <
210 const Name extends string,
211 TableSchema extends AnySchemaStruct,
212 const Indexes extends Record<
213 string,
214 IndexedDbQueryBuilder.KeyPath<TableSchema>
215 >,
216 const KeyPath extends
217 | (AutoIncrement extends true ? IndexedDbQueryBuilder.KeyPathNumber<NoInfer<TableSchema>>
218 : IndexedDbQueryBuilder.KeyPath<NoInfer<TableSchema>>)
219 | undefined = undefined,
220 const AutoIncrement extends boolean = false
221 >(options: {
222 readonly name: Name
223 readonly schema: [KeyPath] extends [undefined]
224 ? "key" extends keyof TableSchema["fields"] ? "Cannot have a 'key' field when keyPath is undefined"
225 : TableSchema
226 : TableSchema
227 readonly keyPath?: KeyPath
228 readonly indexes?: Indexes | undefined
229 readonly autoIncrement?: IsValidAutoIncrementKeyPath<
230 TableSchema,
231 KeyPath
232 > extends true ? AutoIncrement | undefined
233 : never
234 readonly durability?: IDBTransactionDurability | undefined
235 }): IndexedDbTable<
236 Name,
237 TableSchema,
238 Indexes,
239 Extract<KeyPath, Readonly<IDBValidKey | undefined>>,
240 AutoIncrement
241 > => {
242 // oxlint-disable-next-line typescript/no-extraneous-class
243 class Table {}
244 Object.assign(Table, Proto)
245 const readSchema = options.keyPath === undefined
246 ? Schema.Struct({
247 ...(options.schema as Schema.Struct<{}>).fields,
248 key: IndexedDb.IDBValidKey
249 })
250 : options.schema
251 ;(Table as any).tableName = options.name
252 ;(Table as any).tableSchema = options.schema
253 ;(Table as any).readSchema = readSchema
254 ;(Table as any).arraySchema = Schema.Array(readSchema as any)
255 ;(Table as any).autoincrementSchema = options.autoIncrement
256 ? Schema.Struct(Struct.omit((options.schema as Schema.Struct<{}>).fields, [options.keyPath!] as any))
257 : options.schema
258 ;(Table as any).keyPath = options.keyPath
259 ;(Table as any).indexes = options.indexes
260 ;(Table as any).autoIncrement = options.autoIncrement === true
261 ;(Table as any).durability = options.durability ?? "relaxed"
262 return Table as any
263 }
264
265 // -----------------------------------------------------------------------------
266 // internal
267 // -----------------------------------------------------------------------------
268
269 type IsValidAutoIncrementKeyPath<
270 TableSchema extends AnySchemaStruct,
271 KeyPath
272 > = KeyPath extends keyof TableSchema["Encoded"] ? TableSchema["Encoded"][KeyPath] extends number ? true
273 : false
274 : false