@pol-studios/powersync 1.0.10 → 1.0.12

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.
@@ -0,0 +1,257 @@
1
+ /**
2
+ * Configuration types and helpers for PowerSync schema generator
3
+ */
4
+ interface TableConfig {
5
+ /** Table name (PascalCase as it appears in database.types.ts) */
6
+ name: string;
7
+ /** Schema name (defaults to 'public') */
8
+ schema?: string;
9
+ /** Enable ps_crud timestamp tracking for optimistic UI updates */
10
+ trackMetadata?: boolean;
11
+ /**
12
+ * Sync the primary key column (normally skipped as PowerSync handles it internally).
13
+ *
14
+ * Use this for tables with integer PKs that are referenced by FKs in other tables.
15
+ * Example: `Group.id` is referenced by `UserGroup.groupId`, so Group needs `syncPrimaryKey: true`
16
+ * to ensure the integer ID is available for client-side joins.
17
+ */
18
+ syncPrimaryKey?: boolean;
19
+ /** @deprecated Use `syncPrimaryKey` instead */
20
+ includeId?: boolean;
21
+ /** Columns to skip for this specific table (in addition to global skipColumns) */
22
+ skipColumns?: string[];
23
+ /** Only include these columns (overrides skipColumns if specified) */
24
+ onlyColumns?: string[];
25
+ }
26
+ interface GeneratorConfig {
27
+ /** Path to Supabase-generated database.types.ts file */
28
+ typesPath: string;
29
+ /** Output path for generated PowerSync schema */
30
+ outputPath: string;
31
+ /** Tables to include in the PowerSync schema */
32
+ tables: TableConfig[];
33
+ /** Columns to always skip (in addition to defaults like 'id') */
34
+ skipColumns?: string[];
35
+ /** Column name patterns that should use column.real for decimal values */
36
+ decimalPatterns?: string[];
37
+ /** Additional schemas to track (besides 'public' which is the default) */
38
+ schemas?: string[];
39
+ /** Generate indexes for FK and common columns (default: true) */
40
+ autoIndexes?: boolean;
41
+ /** Additional columns to index (exact column names) */
42
+ indexColumns?: string[];
43
+ /** Column patterns that should be indexed (regex patterns) */
44
+ indexPatterns?: string[];
45
+ }
46
+ /**
47
+ * Define a PowerSync generator configuration with type safety
48
+ */
49
+ declare function defineConfig(config: GeneratorConfig): GeneratorConfig;
50
+ /**
51
+ * Default columns that are skipped during generation
52
+ */
53
+ declare const DEFAULT_SKIP_COLUMNS: string[];
54
+ /**
55
+ * Default column name patterns that indicate decimal values
56
+ */
57
+ declare const DEFAULT_DECIMAL_PATTERNS: string[];
58
+ /**
59
+ * Default column patterns that should be indexed
60
+ * These are regex patterns matched against column names
61
+ */
62
+ declare const DEFAULT_INDEX_PATTERNS: string[];
63
+
64
+ /**
65
+ * Parser for Supabase database.types.ts files
66
+ *
67
+ * Extracts table definitions and column types from the generated TypeScript types
68
+ */
69
+
70
+ interface ColumnInfo {
71
+ name: string;
72
+ tsType: string;
73
+ isNullable: boolean;
74
+ }
75
+ interface ParsedTable {
76
+ name: string;
77
+ schema: string;
78
+ columns: Map<string, string>;
79
+ config: TableConfig;
80
+ }
81
+ interface ParseOptions {
82
+ /** Columns to skip */
83
+ skipColumns: Set<string>;
84
+ /**
85
+ * Include the id column (normally skipped).
86
+ * Use for tables with integer PKs referenced by FKs in other tables.
87
+ */
88
+ syncPrimaryKey?: boolean;
89
+ /** @deprecated Use `syncPrimaryKey` instead */
90
+ includeId?: boolean;
91
+ }
92
+ /**
93
+ * Parse the Row type from a table definition and extract columns
94
+ */
95
+ declare function parseRowType(tableContent: string, options: ParseOptions): Map<string, string>;
96
+ /**
97
+ * Extract a table definition from the database.types.ts content
98
+ */
99
+ declare function extractTableDef(content: string, tableName: string, schema: string): string | null;
100
+ /**
101
+ * Parse a database.types.ts file and extract specified tables
102
+ */
103
+ declare function parseTypesFile(content: string, tables: TableConfig[], skipColumns: Set<string>): ParsedTable[];
104
+ /**
105
+ * Get all available schemas from the types file
106
+ */
107
+ declare function getAvailableSchemas(content: string): string[];
108
+ /**
109
+ * Get all table names in a schema
110
+ */
111
+ declare function getTablesInSchema(content: string, schema: string): string[];
112
+
113
+ /**
114
+ * Foreign Key Dependency Detection
115
+ *
116
+ * Analyzes parsed tables to detect FK relationships and determine
117
+ * optimal upload order for offline-first sync.
118
+ */
119
+
120
+ interface FKDependency {
121
+ /** Table containing the FK column */
122
+ table: string;
123
+ /** FK column name (e.g., 'projectId') */
124
+ column: string;
125
+ /** Referenced table name (e.g., 'Project') */
126
+ referencedTable: string;
127
+ }
128
+ interface DependencyGraph {
129
+ /** Map of table -> tables it depends on (has FK references to) */
130
+ dependencies: Map<string, string[]>;
131
+ /** Map of table -> tables that depend on it (have FKs referencing this table) */
132
+ dependents: Map<string, string[]>;
133
+ /** Topologically sorted table names for optimal upload order */
134
+ uploadOrder: string[];
135
+ /** All detected FK relationships */
136
+ fkRelationships: FKDependency[];
137
+ }
138
+ /**
139
+ * Convert a FK column name to its referenced table name
140
+ * Convention: columns ending in 'Id' reference the PascalCase table
141
+ * e.g., projectId -> Project, equipmentUnitId -> EquipmentUnit
142
+ */
143
+ declare function fkColumnToTableName(columnName: string): string | null;
144
+ /**
145
+ * Detect FK dependencies from parsed tables
146
+ *
147
+ * Uses naming convention: columns ending in 'Id' reference the PascalCase table
148
+ * Only considers references to tables that are in the provided list (ignores external references)
149
+ */
150
+ declare function detectFKDependencies(tables: ParsedTable[]): DependencyGraph;
151
+ /**
152
+ * Get optimal upload order using Kahn's topological sort algorithm
153
+ *
154
+ * Tables with no dependencies are uploaded first, then tables that depend on them, etc.
155
+ * This ensures that when a row references another table, the referenced row exists first.
156
+ */
157
+ declare function getUploadOrder(graph: Pick<DependencyGraph, 'dependencies'>): string[];
158
+ /**
159
+ * Get tables that have no dependencies (root tables)
160
+ * These are typically reference/lookup tables like User, Project, etc.
161
+ */
162
+ declare function getRootTables(graph: DependencyGraph): string[];
163
+ /**
164
+ * Get tables that have no dependents (leaf tables)
165
+ * These are typically transaction/event tables that reference other tables
166
+ */
167
+ declare function getLeafTables(graph: DependencyGraph): string[];
168
+ /**
169
+ * Format the dependency graph as a human-readable string
170
+ */
171
+ declare function formatDependencyGraph(graph: DependencyGraph): string;
172
+
173
+ /**
174
+ * PowerSync schema generator
175
+ *
176
+ * Converts Supabase database.types.ts into PowerSync schema definitions
177
+ */
178
+
179
+ interface ColumnMapping {
180
+ type: 'column.text' | 'column.integer' | 'column.real';
181
+ isEnum?: boolean;
182
+ isBoolean?: boolean;
183
+ }
184
+ interface GenerateResult {
185
+ success: boolean;
186
+ tablesGenerated: number;
187
+ outputPath: string;
188
+ errors: string[];
189
+ warnings: string[];
190
+ /** Generated output (included when dryRun is true) */
191
+ output?: string;
192
+ /** Number of indexes generated */
193
+ indexesGenerated?: number;
194
+ /** FK dependency graph (when detected) */
195
+ dependencyGraph?: DependencyGraph;
196
+ }
197
+ /**
198
+ * Map TypeScript types to PowerSync column types
199
+ */
200
+ declare function mapTypeToPowerSync(tsType: string, columnName: string, decimalPatterns: string[]): ColumnMapping | null;
201
+ /**
202
+ * Generate column definitions for a table
203
+ */
204
+ declare function generateColumnDefs(table: ParsedTable, decimalPatterns: string[]): string[];
205
+ /**
206
+ * Generate PowerSync schema from configuration
207
+ */
208
+ declare function generateSchema(config: GeneratorConfig, options?: {
209
+ cwd?: string;
210
+ verbose?: boolean;
211
+ dryRun?: boolean;
212
+ }): Promise<GenerateResult>;
213
+
214
+ /**
215
+ * Output templates for PowerSync schema generation
216
+ */
217
+
218
+ interface IndexDefinition {
219
+ name: string;
220
+ columns: string[];
221
+ }
222
+ /**
223
+ * Generate index definitions for a table based on column patterns
224
+ *
225
+ * @param tableName - The table name (PascalCase)
226
+ * @param columns - Array of column names in the table
227
+ * @param indexPatterns - Regex patterns to match against column names
228
+ * @param additionalColumns - Specific column names to always index
229
+ * @returns Array of index definitions
230
+ */
231
+ declare function generateIndexDefinitions(tableName: string, columns: string[], indexPatterns: string[], additionalColumns?: string[]): IndexDefinition[];
232
+ /**
233
+ * File header template
234
+ */
235
+ declare function generateHeader(typesPath: string): string;
236
+ /**
237
+ * Generate the table definition for a parsed table
238
+ */
239
+ declare function generateTableDefinition(table: ParsedTable, columnDefs: string[], indexes?: IndexDefinition[]): string;
240
+ /**
241
+ * Generate the schema export section
242
+ */
243
+ declare function generateSchemaExport(tableNames: string[]): string;
244
+ /**
245
+ * Generate schema mapping utilities
246
+ */
247
+ declare function generateSchemaMapping(tables: ParsedTable[], schemas: string[]): string;
248
+ /**
249
+ * Generate the FK detection utility (helpful for consumers)
250
+ */
251
+ declare function generateFKUtility(): string;
252
+ /**
253
+ * Generate complete output file
254
+ */
255
+ declare function generateOutputFile(tables: ParsedTable[], tableDefs: string[], schemas: string[], typesPath: string): string;
256
+
257
+ export { type ColumnInfo, type ColumnMapping, DEFAULT_DECIMAL_PATTERNS, DEFAULT_INDEX_PATTERNS, DEFAULT_SKIP_COLUMNS, type DependencyGraph, type FKDependency, type GenerateResult, type GeneratorConfig, type IndexDefinition, type ParseOptions, type ParsedTable, type TableConfig, defineConfig, detectFKDependencies, extractTableDef, fkColumnToTableName, formatDependencyGraph, generateColumnDefs, generateFKUtility, generateHeader, generateIndexDefinitions, generateOutputFile, generateSchema, generateSchemaExport, generateSchemaMapping, generateTableDefinition, getAvailableSchemas, getLeafTables, getRootTables, getTablesInSchema, getUploadOrder, mapTypeToPowerSync, parseRowType, parseTypesFile };