skyward-orm 0.3.0 → 0.4.0

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.
Files changed (96) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +200 -31
  3. data/lib/skyward/orm/adapters/postgresql.rb +140 -38
  4. data/lib/skyward/orm/adapters/sqlite/constraints.rb +18 -0
  5. data/lib/skyward/orm/adapters/sqlite.rb +130 -21
  6. data/lib/skyward/orm/adapters.rb +12 -2
  7. data/lib/skyward/orm/catalog/column.rb +2 -1
  8. data/lib/skyward/orm/cli/boot_file.rb +2 -2
  9. data/lib/skyward/orm/cli/migrate.rb +1 -1
  10. data/lib/skyward/orm/cli/migration.rb +1 -1
  11. data/lib/skyward/orm/cli/scaffold/source.rb +304 -0
  12. data/lib/skyward/orm/cli/scaffold.rb +70 -0
  13. data/lib/skyward/orm/cli/status.rb +5 -3
  14. data/lib/skyward/orm/commands.rb +12 -0
  15. data/lib/skyward/orm/connection/instrumented.rb +69 -0
  16. data/lib/skyward/orm/connection/session.rb +74 -5
  17. data/lib/skyward/orm/{connection/database → database}/schema_check.rb +20 -8
  18. data/lib/skyward/orm/{connection/database.rb → database.rb} +15 -15
  19. data/lib/skyward/orm/execution.rb +9 -0
  20. data/lib/skyward/orm/migrations/alter_table.rb +6 -2
  21. data/lib/skyward/orm/migrations/definitions.rb +7 -4
  22. data/lib/skyward/orm/migrations/diff.rb +154 -30
  23. data/lib/skyward/orm/migrations/rename_constraint.rb +8 -0
  24. data/lib/skyward/orm/migrations/runner.rb +13 -3
  25. data/lib/skyward/orm/migrations/script.rb +60 -20
  26. data/lib/skyward/orm/migrations/status.rb +32 -3
  27. data/lib/skyward/orm/migrations/summary.rb +3 -6
  28. data/lib/skyward/orm/migrations/versions.rb +1 -1
  29. data/lib/skyward/orm/migrations.rb +1 -1
  30. data/lib/skyward/orm/projection.rb +23 -4
  31. data/lib/skyward/orm/queries/clauses.rb +117 -32
  32. data/lib/skyward/orm/record.rb +23 -1
  33. data/lib/skyward/orm/{placeholders.rb → statements/placeholders.rb} +1 -1
  34. data/lib/skyward/orm/statements.rb +171 -30
  35. data/lib/skyward/orm/tables/column.rb +2 -1
  36. data/lib/skyward/orm/tables/column_types.rb +62 -15
  37. data/lib/skyward/orm/tables/declarations.rb +38 -10
  38. data/lib/skyward/orm/{members.rb → tables/members.rb} +1 -1
  39. data/lib/skyward/orm/tables/sources.rb +63 -0
  40. data/lib/skyward/orm/tables/validation.rb +12 -3
  41. data/lib/skyward/orm/tables/values.rb +115 -5
  42. data/lib/skyward/orm/tables.rb +2 -1
  43. data/lib/skyward/orm/transactional.rb +2 -2
  44. data/lib/skyward/orm/version.rb +1 -1
  45. data/lib/skyward/orm.rb +44 -10
  46. data/sig/generated/skyward/orm/adapters/postgresql.rbs +53 -14
  47. data/sig/generated/skyward/orm/adapters/sqlite/constraints.rbs +6 -0
  48. data/sig/generated/skyward/orm/adapters/sqlite.rbs +67 -7
  49. data/sig/generated/skyward/orm/adapters.rbs +3 -0
  50. data/sig/generated/skyward/orm/catalog/column.rbs +6 -4
  51. data/sig/generated/skyward/orm/cli/boot_file.rbs +4 -4
  52. data/sig/generated/skyward/orm/cli/migrate.rbs +2 -2
  53. data/sig/generated/skyward/orm/cli/migration.rbs +2 -2
  54. data/sig/generated/skyward/orm/cli/scaffold/source.rbs +147 -0
  55. data/sig/generated/skyward/orm/cli/scaffold.rbs +28 -0
  56. data/sig/generated/skyward/orm/cli/status.rbs +2 -2
  57. data/sig/generated/skyward/orm/connection/instrumented.rbs +45 -0
  58. data/sig/generated/skyward/orm/connection/session.rbs +40 -6
  59. data/sig/generated/skyward/orm/{connection/database → database}/schema_check.rbs +11 -4
  60. data/sig/generated/skyward/orm/{connection/database.rbs → database.rbs} +4 -5
  61. data/sig/generated/skyward/orm/execution.rbs +18 -0
  62. data/sig/generated/skyward/orm/migrations/alter_table.rbs +11 -5
  63. data/sig/generated/skyward/orm/migrations/definitions.rbs +2 -2
  64. data/sig/generated/skyward/orm/migrations/diff.rbs +77 -11
  65. data/sig/generated/skyward/orm/migrations/rename_constraint.rbs +16 -0
  66. data/sig/generated/skyward/orm/migrations/runner.rbs +5 -0
  67. data/sig/generated/skyward/orm/migrations/script.rbs +32 -8
  68. data/sig/generated/skyward/orm/migrations/status.rbs +15 -2
  69. data/sig/generated/skyward/orm/migrations/summary.rbs +0 -1
  70. data/sig/generated/skyward/orm/migrations/versions.rbs +2 -2
  71. data/sig/generated/skyward/orm/migrations.rbs +1 -1
  72. data/sig/generated/skyward/orm/projection.rbs +10 -2
  73. data/sig/generated/skyward/orm/queries/clauses.rbs +60 -24
  74. data/sig/generated/skyward/orm/record.rbs +8 -0
  75. data/sig/generated/skyward/orm/{placeholders.rbs → statements/placeholders.rbs} +2 -2
  76. data/sig/generated/skyward/orm/statements.rbs +83 -5
  77. data/sig/generated/skyward/orm/tables/column.rbs +6 -4
  78. data/sig/generated/skyward/orm/tables/column_types.rbs +18 -4
  79. data/sig/generated/skyward/orm/tables/declarations.rbs +15 -1
  80. data/sig/generated/skyward/orm/{members.rbs → tables/members.rbs} +2 -2
  81. data/sig/generated/skyward/orm/tables/sources.rbs +32 -0
  82. data/sig/generated/skyward/orm/tables/values.rbs +41 -1
  83. data/sig/generated/skyward/orm/tables.rbs +3 -1
  84. data/sig/generated/skyward/orm.rbs +6 -6
  85. data/sig/manual/pg.rbs +12 -0
  86. data/sig/manual/skyward/orm/cli/scaffold/source.rbs +3 -0
  87. data/sig/manual/skyward/orm/cli/scaffold.rbs +3 -0
  88. data/sig/manual/skyward/orm/database/schema_check.rbs +3 -0
  89. data/sig/manual/skyward/orm/statements/placeholders.rbs +3 -0
  90. data/sig/manual/skyward/orm/tables/members.rbs +3 -0
  91. data/sig/manual/skyward/orm/tables/sources.rbs +3 -0
  92. data/sig/manual/skyward/orm.rbs +32 -5
  93. metadata +43 -14
  94. data/sig/manual/skyward/orm/connection/database/schema_check.rbs +0 -3
  95. data/sig/manual/skyward/orm/members.rbs +0 -3
  96. data/sig/manual/skyward/orm/placeholders.rbs +0 -3
@@ -5,32 +5,78 @@ module Skyward::ORM::Statements
5
5
 
6
6
  # @rbs adapter: Skyward::ORM::_Adapter
7
7
  # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
8
+ # @rbs tables: Array[Skyward::ORM::Catalog::Table]
8
9
  # @rbs table: singleton(Skyward::ORM::Record)
9
10
  # @rbs values: Hash[Symbol, untyped]
10
11
  # @rbs return: [String, Array[untyped]]
11
- def insert(adapter, column_types, table, values)
12
- require_values(column_types, table, values)
13
- require_present(table, column_types.columns(table), values.keys)
14
- into = "INSERT INTO #{quote(table.table_name)}"
15
- return ["#{into} DEFAULT VALUES", []] if values.empty?
12
+ def insert(adapter, column_types, tables, table, values)
13
+ require_values(column_types, tables, table, values)
14
+ require_present(table, column_types.columns(table), values.keys, generated(tables, table), "#{table}.insert")
15
+ return ["INSERT INTO #{quote(table.table_name)} DEFAULT VALUES", []] if values.empty?
16
16
 
17
- placeholders = Array.new(values.size) { |index| adapter.placeholder(index + 1) }
18
- [
19
- "#{into} (#{values.keys.map { |column| quote(column) }.join(", ")}) VALUES (#{placeholders.join(", ")})",
20
- values.values.map { |value| adapter.encode(value) }
21
- ]
17
+ inserting(adapter, column_types, table, values.keys, [values])
18
+ end
19
+
20
+ # @rbs adapter: Skyward::ORM::_Adapter
21
+ # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
22
+ # @rbs tables: Array[Skyward::ORM::Catalog::Table]
23
+ # @rbs table: singleton(Skyward::ORM::Record)
24
+ # @rbs rows: Array[Hash[Symbol, untyped]]
25
+ # @rbs return: [String, Array[untyped]]
26
+ def insert_all(adapter, column_types, tables, table, rows)
27
+ columns = rows.fetch(0).keys
28
+ # Neither database takes DEFAULT VALUES for more than one row.
29
+ if columns.empty?
30
+ raise ArgumentError, "#{table}.insert_all row 0 has no columns. Use #{table}.insert for a row of defaults."
31
+ end
32
+
33
+ require_bindable(adapter, table, rows.size, columns.size)
34
+ generated = generated(tables, table)
35
+ rows.each_with_index do |row, index|
36
+ subject = "#{table}.insert_all row #{index}"
37
+ require_alike(subject, columns, row.keys)
38
+ refused = unwritable(column_types, generated, table, row)
39
+ raise ArgumentError, "#{subject}: #{refused}" if refused
40
+ end
41
+ # Every row has row 0's columns by now, so only row 0 can lack one.
42
+ require_present(table, column_types.columns(table), columns, generated, "#{table}.insert_all row 0")
43
+ inserting(adapter, column_types, table, columns, rows)
44
+ end
45
+
46
+ # @rbs adapter: Skyward::ORM::_Adapter
47
+ # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
48
+ # @rbs table: singleton(Skyward::ORM::Record)
49
+ # @rbs values: Hash[Symbol, untyped]
50
+ # @rbs return: Array[untyped]
51
+ def binds(adapter, column_types, table, values)
52
+ columns = by_name(column_types, table)
53
+ values.map { |name, value| encode(adapter, columns.fetch(name), value) }
54
+ end
55
+
56
+ # Only a column says a Hash is JSON, or an Array one value: bound to a ? in
57
+ # SQL, either is refused, since the driver would spread it across
58
+ # placeholders. And only a column says an Integer is a decimal, whose text
59
+ # SQLite compares, so 2 is bound as 2.0, as BigDecimal(2) is.
60
+ # @rbs adapter: Skyward::ORM::_Adapter
61
+ # @rbs column: Skyward::ORM::Tables::Column
62
+ # @rbs value: untyped
63
+ # @rbs return: untyped
64
+ def encode(adapter, column, value)
65
+ return if value.nil?
66
+
67
+ case column.type
68
+ when :json then JSON.generate(value)
69
+ when :array then adapter.encode_array(value.map { |item| exact(column.element, item) })
70
+ else adapter.encode(exact(column.type, value))
71
+ end
22
72
  end
23
73
 
24
74
  # @rbs table: singleton(Skyward::ORM::Record)
25
75
  # @rbs columns: Array[Symbol]
26
76
  # @rbs return: void
27
77
  def require_columns(table, columns)
28
- known = table.schema.columns
29
- unknown = (columns - known).first #: Symbol?
30
- return unless unknown
31
-
32
- suggestion = DidYouMean::SpellChecker.new(dictionary: known).correct(unknown).first
33
- raise ArgumentError, "#{table} has no column #{unknown}.#{" Did you mean #{suggestion}?" if suggestion}"
78
+ refused = unknown(table, columns)
79
+ raise ArgumentError, refused if refused
34
80
  end
35
81
 
36
82
  # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
@@ -38,21 +84,27 @@ module Skyward::ORM::Statements
38
84
  # @rbs conditions: Hash[Symbol, untyped]
39
85
  # @rbs return: void
40
86
  def require_conditions(column_types, table, conditions)
41
- refuse(column_types, table, conditions) do |column, value|
87
+ refused = refusal(column_types, table, conditions) do |column, value|
42
88
  Skyward::ORM::Tables::Values.mismatch(table, column, value)
43
89
  end
90
+ raise ArgumentError, refused if refused
44
91
  end
45
92
 
46
93
  # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
94
+ # @rbs tables: Array[Skyward::ORM::Catalog::Table]
47
95
  # @rbs table: singleton(Skyward::ORM::Record)
48
96
  # @rbs values: Hash[Symbol, untyped]
49
97
  # @rbs return: void
50
- def require_values(column_types, table, values)
51
- refuse(column_types, table, values) do |column, value|
52
- Skyward::ORM::Tables::Values.write_mismatch(table, column, value)
53
- end
98
+ def require_values(column_types, tables, table, values)
99
+ refused = unwritable(column_types, generated(tables, table), table, values)
100
+ raise ArgumentError, refused if refused
54
101
  end
55
102
 
103
+ # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
104
+ # @rbs table: singleton(Skyward::ORM::Record)
105
+ # @rbs return: Hash[Symbol, Skyward::ORM::Tables::Column]
106
+ def by_name(column_types, table) = column_types.columns(table).to_h { |column| [column.name, column] }
107
+
56
108
  # @rbs columns: Array[Symbol]
57
109
  # @rbs return: String
58
110
  def returning(columns) = "RETURNING #{columns.map { |column| quote(column) }.join(", ")}"
@@ -64,16 +116,73 @@ module Skyward::ORM::Statements
64
116
 
65
117
  private
66
118
 
119
+ # @rbs type: Skyward::ORM::Tables::column_type?
120
+ # @rbs value: untyped
121
+ # @rbs return: untyped
122
+ def exact(type, value) = type == :decimal && value.is_a?(Integer) ? BigDecimal(value) : value
123
+
124
+ # @rbs adapter: Skyward::ORM::_Adapter
125
+ # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
126
+ # @rbs table: singleton(Skyward::ORM::Record)
127
+ # @rbs columns: Array[Symbol]
128
+ # @rbs rows: Array[Hash[Symbol, untyped]]
129
+ # @rbs return: [String, Array[untyped]]
130
+ def inserting(adapter, column_types, table, columns, rows)
131
+ tuples = Array.new(rows.size * columns.size) { |index| adapter.placeholder(index + 1) }
132
+ .each_slice(columns.size).map { |placeholders| "(#{placeholders.join(", ")})" }
133
+ named = by_name(column_types, table)
134
+ [
135
+ "INSERT INTO #{quote(table.table_name)} (#{columns.map { |column| quote(column) }.join(", ")}) " \
136
+ "VALUES #{tuples.join(", ")}",
137
+ rows.flat_map { |row| columns.map { |column| encode(adapter, named.fetch(column), row.fetch(column)) } }
138
+ ]
139
+ end
140
+
141
+ # @rbs table: singleton(Skyward::ORM::Record)
142
+ # @rbs columns: Array[Symbol]
143
+ # @rbs return: String?
144
+ def unknown(table, columns)
145
+ known = table.schema.columns
146
+ name = (columns - known).first #: Symbol?
147
+ return unless name
148
+
149
+ suggestion = Skyward::Core::Diagnostics::Suggestion.closest(name.to_s, known.map(&:to_s))
150
+ "#{table} has no column #{name}.#{" Did you mean #{suggestion}?" if suggestion}"
151
+ end
152
+
153
+ # @rbs tables: Array[Skyward::ORM::Catalog::Table]
154
+ # @rbs table: singleton(Skyward::ORM::Record)
155
+ # @rbs return: Array[Symbol]
156
+ def generated(tables, table)
157
+ found = tables.find { |candidate| candidate.name == table.table_name }
158
+ found ? found.columns.select(&:generated).map(&:name) : []
159
+ end
160
+
161
+ # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
162
+ # @rbs generated: Array[Symbol]
163
+ # @rbs table: singleton(Skyward::ORM::Record)
164
+ # @rbs values: Hash[Symbol, untyped]
165
+ # @rbs return: String?
166
+ def unwritable(column_types, generated, table, values)
167
+ written = (values.keys & generated).first
168
+ return "#{table}.#{written} is generated by the database, so it can't be written" if written
169
+
170
+ refusal(column_types, table, values) do |column, value|
171
+ Skyward::ORM::Tables::Values.write_mismatch(table, column, value)
172
+ end
173
+ end
174
+
67
175
  # @rbs column_types: Skyward::ORM::Tables::ColumnTypes
68
176
  # @rbs table: singleton(Skyward::ORM::Record)
69
177
  # @rbs values: Hash[Symbol, untyped]
70
178
  # @rbs &: (Skyward::ORM::Tables::Column column, untyped value) -> String?
71
- # @rbs return: void
72
- def refuse(column_types, table, values)
73
- require_columns(table, values.keys)
74
- columns = column_types.columns(table).to_h { |column| [column.name, column] }
75
- refused = values.filter_map { |name, value| yield(columns.fetch(name), value) }.first
76
- raise ArgumentError, refused if refused
179
+ # @rbs return: String?
180
+ def refusal(column_types, table, values)
181
+ refused = unknown(table, values.keys)
182
+ return refused if refused
183
+
184
+ columns = by_name(column_types, table)
185
+ values.filter_map { |name, value| yield(columns.fetch(name), value) }.first
77
186
  end
78
187
 
79
188
  # An untyped column's nullability is unknown, so it's left to the database,
@@ -81,17 +190,49 @@ module Skyward::ORM::Statements
81
190
  # @rbs table: singleton(Skyward::ORM::Record)
82
191
  # @rbs columns: Array[Skyward::ORM::Tables::Column]
83
192
  # @rbs given: Array[Symbol]
193
+ # @rbs generated: Array[Symbol]
194
+ # @rbs subject: String
84
195
  # @rbs return: void
85
- def require_present(table, columns, given)
196
+ def require_present(table, columns, given, generated, subject)
86
197
  schema = table.schema
87
198
  required = columns.reject do |column|
88
199
  column.nullable || column.type == :untyped || column.name == schema.primary_key ||
89
- schema.defaults.key?(column.name)
200
+ schema.defaults.key?(column.name) || generated.include?(column.name)
90
201
  end
91
202
  missing = required.map(&:name) - given
92
203
  return if missing.empty?
93
204
 
94
205
  raise ArgumentError,
95
- "#{table}.insert needs #{missing.join(", ")}: a column that can't be NULL and has no default needs a value"
206
+ "#{subject} needs #{missing.join(", ")}: a column that can't be NULL and has no default needs a value"
207
+ end
208
+
209
+ # Matched as sets, since each row's values are read in the first row's order.
210
+ # @rbs subject: String
211
+ # @rbs columns: Array[Symbol]
212
+ # @rbs given: Array[Symbol]
213
+ # @rbs return: void
214
+ def require_alike(subject, columns, given)
215
+ differences = { "has" => given - columns, "lacks" => columns - given }.reject { |_, names| names.empty? }
216
+ return if differences.empty?
217
+
218
+ raise ArgumentError,
219
+ "#{subject} #{differences.map { |verb, names| "#{verb} #{names.join(", ")}" }.join(" and ")}, " \
220
+ "unlike row 0: every row needs the same columns"
221
+ end
222
+
223
+ # @rbs adapter: Skyward::ORM::_Adapter
224
+ # @rbs table: singleton(Skyward::ORM::Record)
225
+ # @rbs rows: Integer
226
+ # @rbs columns: Integer
227
+ # @rbs return: void
228
+ def require_bindable(adapter, table, rows, columns)
229
+ limit = adapter.bind_limit
230
+ binds = rows * columns
231
+ return if binds <= limit
232
+
233
+ raise ArgumentError,
234
+ "#{table}.insert_all binds #{binds} values, #{columns} for each of #{rows} rows, but the " \
235
+ "database binds at most #{limit} in one statement. Split the rows, in a Skyward.transaction if they " \
236
+ "must land together."
96
237
  end
97
238
  end
@@ -5,6 +5,7 @@ module Skyward::ORM::Tables
5
5
  :name, #: Symbol
6
6
  :type, #: column_type
7
7
  :nullable, #: bool
8
- :symbols #: Array[Symbol]
8
+ :symbols, #: Array[Symbol]
9
+ :element #: column_type?
9
10
  )
10
11
  end
@@ -6,8 +6,20 @@ class Skyward::ORM::Tables::ColumnTypes
6
6
 
7
7
  UNTYPED = Skyward::Core::Types::Scalar.new(name: :untyped) #: Skyward::Core::Types::Scalar
8
8
 
9
- COLUMN_TYPES = "A column is Integer, Float, String, bool, Date, Time or a union of symbols, " \
10
- "any of them nullable, or untyped." #: String
9
+ COLUMN_TYPES = "A column is Integer, Float, BigDecimal, String, bool, Date, Time, uuid, int32, int16, " \
10
+ "a union of symbols, Hash[String, untyped] or Array[T], any of them nullable, or untyped." #: String
11
+
12
+ ELEMENTS = %i[integer float decimal string bool date time].freeze #: Array[Skyward::Core::Types::scalar]
13
+
14
+ ELEMENT_TYPES = "An Array column is Array[T], where T is Integer, Float, BigDecimal, String, bool, Date, Time " \
15
+ "or a union of symbols, and isn't nullable." #: String
16
+
17
+ # The aliases Skyward ORM declares, for its reader to keep as the column type each names.
18
+ REFINEMENTS = {
19
+ "::Skyward::ORM::uuid" => :uuid,
20
+ "::Skyward::ORM::int32" => :int32,
21
+ "::Skyward::ORM::int16" => :int16
22
+ }.freeze #: Hash[String, Skyward::ORM::Tables::refinement]
11
23
 
12
24
  # @rbs reader: Skyward::Core::Types::Reader
13
25
  # @rbs return: void
@@ -28,13 +40,17 @@ class Skyward::ORM::Tables::ColumnTypes
28
40
  # @rbs return: Array[Skyward::ORM::Tables::Column]
29
41
  def resolve(klass)
30
42
  type_name = @reader.type_name(klass)
31
- Skyward::ORM::Members.of(klass).map do |name|
43
+ Skyward::ORM::Tables::Members.of(klass).map do |name|
32
44
  returned = @reader.method_type(type_name, name)&.type&.return_type if type_name
33
45
  written = returned.to_s.gsub(/(?<!\w)::/, "")
34
46
  column = returned ? read(name, returned, written) : column(name, UNTYPED, written)
35
47
  case column
36
- when String then raise Skyward::Core::BootError, "#{klass}##{name} #{column}"
37
- else column
48
+ when Skyward::ORM::Tables::Column then column
49
+ else
50
+ problem, suggestion = column
51
+ spot = Skyward::ORM::Tables::Sources.reader(klass, name)
52
+ raise Skyward::Core::BootError,
53
+ Skyward::ORM::Tables::Sources.explain("#{klass}##{name} #{problem}", [spot], suggestion)
38
54
  end
39
55
  end.freeze
40
56
  end
@@ -42,33 +58,64 @@ class Skyward::ORM::Tables::ColumnTypes
42
58
  # @rbs name: Symbol
43
59
  # @rbs returned: RBS::Types::t
44
60
  # @rbs written: String
45
- # @rbs return: Skyward::ORM::Tables::Column | String
61
+ # @rbs return: Skyward::ORM::Tables::Column | [String, String?]
46
62
  def read(name, returned, written)
47
63
  column(name, @reader.read(returned), written)
48
64
  # The reader raises for a type it can't read at all, such as one that refers
49
65
  # to itself, and the column should still be named.
50
66
  rescue Skyward::Core::BootError => e
51
- "is #{written}. #{e.message}"
67
+ ["is #{written}. #{e.message}", nil]
52
68
  end
53
69
 
54
70
  # @rbs name: Symbol
55
71
  # @rbs read: Skyward::Core::Types::result
56
72
  # @rbs written: String
57
- # @rbs return: Skyward::ORM::Tables::Column | String
73
+ # @rbs return: Skyward::ORM::Tables::Column | [String, String?]
58
74
  def column(name, read, written)
59
75
  nullable = read.is_a?(Skyward::Core::Types::Nullable)
60
76
  carried = read.is_a?(Skyward::Core::Types::Nullable) ? read.type : read
61
77
  case carried
78
+ when Skyward::Core::Types::Record, Skyward::Core::Types::Named
79
+ ["is #{written}, which isn't a column type yet. #{COLUMN_TYPES}", nil]
80
+ when Skyward::Core::Types::ArrayOf then array(name, carried.type, nullable, written)
81
+ when Skyward::Core::Types::HashOf
82
+ if carried.type == UNTYPED
83
+ Skyward::ORM::Tables::Column.new(name:, type: :json, nullable:, symbols: [], element: nil)
84
+ else
85
+ ["is #{written}, which isn't a column type. A Hash column is Hash[String, untyped], holding any JSON.", nil]
86
+ end
62
87
  when Skyward::Core::Types::Scalar
63
- Skyward::ORM::Tables::Column.new(name:, type: carried.name, nullable:, symbols: [])
88
+ Skyward::ORM::Tables::Column.new(name:, type: carried.name, nullable:, symbols: [], element: nil)
64
89
  when Skyward::Core::Types::Enum
65
- Skyward::ORM::Tables::Column.new(name:, type: :enum, nullable:, symbols: carried.symbols)
90
+ Skyward::ORM::Tables::Column.new(name:, type: :enum, nullable:, symbols: carried.symbols, element: nil)
91
+ when Skyward::Core::Types::Refined
92
+ # The reader refines only the aliases in REFINEMENTS.
93
+ type = carried.as #: Skyward::ORM::Tables::refinement
94
+ Skyward::ORM::Tables::Column.new(name:, type:, nullable:, symbols: [], element: nil)
66
95
  when Skyward::Core::Types::Unreadable
67
- "can't be read: Skyward ORM doesn't read #{carried.type}#{", at #{carried.at}" if carried.at}. #{COLUMN_TYPES}"
68
- when Skyward::Core::Types::Record, Skyward::Core::Types::Named, Skyward::Core::Types::ArrayOf,
69
- Skyward::Core::Types::HashOf
70
- "is #{written}, which isn't a column type yet. #{COLUMN_TYPES}"
71
- else "is #{written}, which isn't a column type. #{COLUMN_TYPES}"
96
+ at = ", at #{carried.at}" if carried.at
97
+ ["can't be read: Skyward ORM doesn't read #{carried.type}#{at}. #{COLUMN_TYPES}", carried.suggestion]
98
+ else ["is #{written}, which isn't a column type. #{COLUMN_TYPES}", nil]
99
+ end
100
+ end
101
+
102
+ # @rbs name: Symbol
103
+ # @rbs item: Skyward::Core::Types::t
104
+ # @rbs nullable: bool
105
+ # @rbs written: String
106
+ # @rbs return: Skyward::ORM::Tables::Column | [String, String?]
107
+ def array(name, item, nullable, written)
108
+ case item
109
+ when Skyward::Core::Types::Scalar
110
+ if ELEMENTS.include?(item.name)
111
+ Skyward::ORM::Tables::Column.new(name:, type: :array, nullable:, symbols: [], element: item.name)
112
+ else
113
+ ["is #{written}, which isn't a column type. #{ELEMENT_TYPES}", nil]
114
+ end
115
+ when Skyward::Core::Types::Enum
116
+ Skyward::ORM::Tables::Column.new(name:, type: :array, nullable:, symbols: item.symbols, element: :enum)
117
+ when Skyward::Core::Types::Refined then ["is #{written}, which isn't a column type yet. #{ELEMENT_TYPES}", nil]
118
+ else ["is #{written}, which isn't a column type. #{ELEMENT_TYPES}", nil]
72
119
  end
73
120
  end
74
121
  end
@@ -16,13 +16,27 @@ module Skyward::ORM::Tables::Declarations
16
16
  ON_DELETE = %i[cascade restrict set_null set_default no_action].freeze #: Array[Skyward::ORM::Tables::on_delete]
17
17
 
18
18
  # @rbs @schema: Skyward::ORM::Tables::Schema?
19
+ # @rbs @locations: Hash[[Symbol, Symbol], [String, Integer]]?
19
20
 
20
21
  # @rbs return: Skyward::ORM::Tables::Schema
21
22
  def schema = @schema || EMPTY
22
23
 
24
+ # The schema is compared as a value, so where each name was declared is kept
25
+ # beside it, by the declaration and the column or table it names.
26
+ # @rbs declaration: Symbol
27
+ # @rbs name: Symbol
28
+ # @rbs return: [String, Integer]?
29
+ def declared_at(declaration, name) = @locations&.[]([declaration, name])
30
+
23
31
  # @rbs return: Symbol
24
32
  def table_name
25
- schema.table || raise(Skyward::Core::BootError, "#{self} has no table. Add `table :name` to its body.")
33
+ schema.table || raise(
34
+ Skyward::Core::BootError,
35
+ Skyward::ORM::Tables::Sources.explain(
36
+ "#{self} has no table. Add `table :name` to its body.",
37
+ [Skyward::ORM::Tables::Sources.class_name(self)]
38
+ )
39
+ )
26
40
  end
27
41
 
28
42
  # Every attr_reader is a column, so each one compiles the row's methods again.
@@ -35,7 +49,7 @@ module Skyward::ORM::Tables::Declarations
35
49
  repeated = columns.find { |column| columns.count(column) > 1 }
36
50
  raise ArgumentError, "#{self} already has a column #{repeated}" if repeated
37
51
 
38
- declare(columns: columns.freeze)
52
+ declare(:attr_reader, readers, columns: columns.freeze)
39
53
  # Ruby warns when a method is redefined, so the old ones are removed first.
40
54
  (Skyward::ORM::Tables::Rows::METHODS & [*instance_methods(false), *private_instance_methods(false)])
41
55
  .each { |method| remove_method(method) }
@@ -47,7 +61,7 @@ module Skyward::ORM::Tables::Declarations
47
61
  # @rbs return: void
48
62
  def table(name)
49
63
  refuse(:table, [name], "the table's name must be a Symbol, such as :todos") unless symbol?(name)
50
- declare(table: name)
64
+ declare(:table, [name], table: name)
51
65
  end
52
66
 
53
67
  # @rbs column: Symbol
@@ -55,7 +69,7 @@ module Skyward::ORM::Tables::Declarations
55
69
  def primary_key(column)
56
70
  problem = unnamed([column])
57
71
  refuse(:primary_key, [column], problem) if problem
58
- declare(primary_key: column)
72
+ declare(:primary_key, [column], primary_key: column)
59
73
  end
60
74
 
61
75
  # @rbs column: Symbol
@@ -66,13 +80,13 @@ module Skyward::ORM::Tables::Declarations
66
80
  problem = unnamed([column]) || unreferenceable(table, on_delete)
67
81
  refuse(:references, [column], problem) if problem
68
82
  reference = Skyward::ORM::Tables::Reference.new(column:, table:, on_delete:)
69
- declare(references: [*schema.references, reference].freeze)
83
+ declare(:references, [column], references: [*schema.references, reference].freeze)
70
84
  end
71
85
 
72
86
  # @rbs **values: untyped
73
87
  # @rbs return: void
74
88
  def default(**values)
75
- declare(defaults: schema.defaults.merge(values).freeze)
89
+ declare(:default, values.keys, defaults: schema.defaults.merge(values).freeze)
76
90
  end
77
91
 
78
92
  # @rbs *columns: Symbol
@@ -80,7 +94,7 @@ module Skyward::ORM::Tables::Declarations
80
94
  def unique(*columns)
81
95
  problem = unnamed(columns)
82
96
  refuse(:unique, columns, problem) if problem
83
- declare(uniques: [*schema.uniques, columns.freeze].freeze)
97
+ declare(:unique, columns, uniques: [*schema.uniques, columns.freeze].freeze)
84
98
  end
85
99
 
86
100
  # @rbs column: Symbol
@@ -91,7 +105,8 @@ module Skyward::ORM::Tables::Declarations
91
105
  rule = unnamed([column]) || check_rule(sql, length)
92
106
  case rule
93
107
  when String then refuse(:check, [column], rule)
94
- else declare(checks: [*schema.checks, Skyward::ORM::Tables::Check.new(column:, rule:)].freeze)
108
+ else
109
+ declare(:check, [column], checks: [*schema.checks, Skyward::ORM::Tables::Check.new(column:, rule:)].freeze)
95
110
  end
96
111
  end
97
112
 
@@ -100,15 +115,28 @@ module Skyward::ORM::Tables::Declarations
100
115
  def index(*columns)
101
116
  problem = unnamed(columns)
102
117
  refuse(:index, columns, problem) if problem
103
- declare(indexes: [*schema.indexes, columns.freeze].freeze)
118
+ declare(:index, columns, indexes: [*schema.indexes, columns.freeze].freeze)
104
119
  end
105
120
 
106
121
  private
107
122
 
123
+ # Only a declaration calls this, so its caller's caller is the class body.
124
+ # An anonymous class, from Class.new, keeps no location, and eval'd code has
125
+ # no file to point at.
126
+ # @rbs declaration: Symbol
127
+ # @rbs names: Array[Symbol]
108
128
  # @rbs **changes: untyped
109
129
  # @rbs return: void
110
- def declare(**changes)
130
+ def declare(declaration, names, **changes)
111
131
  @schema = schema.with(**changes)
132
+ site = caller_locations(2, 1)&.first
133
+ path = site&.absolute_path
134
+ return unless name && site && path
135
+
136
+ located = names.to_h do |named|
137
+ [[declaration, named], [path, site.lineno]] #: [[Symbol, Symbol], [String, Integer]]
138
+ end
139
+ @locations = (@locations || {}).merge(located)
112
140
  end
113
141
 
114
142
  # @rbs declaration: Symbol
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- module Skyward::ORM::Members
3
+ module Skyward::ORM::Tables::Members
4
4
  extend self
5
5
 
6
6
  KEYWORDS = %i[keyreq key].freeze #: Array[Symbol]
@@ -0,0 +1,63 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::ORM::Tables::Sources
4
+ extend self
5
+
6
+ # @rbs klass: singleton(Skyward::ORM::Record)
7
+ # @rbs declaration: Symbol
8
+ # @rbs name: Symbol
9
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
10
+ def declaration(klass, declaration, name)
11
+ path, line = klass.declared_at(declaration, name)
12
+ return unless path && line
13
+
14
+ case declaration
15
+ when :default then Skyward::Core::Diagnostics::Spots.keyword_key(path, line, call: :default, key: name)
16
+ else Skyward::Core::Diagnostics::Spots.symbol(path, line, call: declaration, value: name)
17
+ end
18
+ end
19
+
20
+ # A type in a hand-written .rbs leaves the reader's line with no type to
21
+ # point at, so the carets go under the column's name.
22
+ # @rbs klass: Class
23
+ # @rbs column: Symbol
24
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
25
+ def reader(klass, column)
26
+ return unless klass <= Skyward::ORM::Record
27
+
28
+ table = klass #: singleton(Skyward::ORM::Record)
29
+ path, line = table.declared_at(:attr_reader, column)
30
+ return unless path && line
31
+
32
+ Skyward::Core::Diagnostics::Spots.reader_type(path, line) ||
33
+ Skyward::Core::Diagnostics::Spots.symbol(path, line, call: :attr_reader, value: column)
34
+ end
35
+
36
+ # Only a `class` keyword's line is pointed at, so a class from Class.new
37
+ # keeps its message even once a constant names it, as its declarations do.
38
+ # @rbs klass: Module
39
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
40
+ def class_name(klass)
41
+ name = klass.name
42
+ # A class in an anonymous module has a temporary name, which const_source_location refuses.
43
+ path, line = Object.const_source_location(name) if name && !name.start_with?("#<")
44
+ return unless name && path && line && File.file?(path)
45
+
46
+ text = File.readlines(path).fetch(line - 1, "").chomp
47
+ start, finish = text.match(/\bclass\s+\K(?:\w+::)*#{Regexp.escape(name.split("::").last.to_s)}\b/)&.offset(0)
48
+ Skyward::Core::Diagnostics::Spot.new(path:, line:, text:, columns: start...finish) if start && finish
49
+ end
50
+
51
+ # @rbs message: String
52
+ # @rbs spots: Array[Skyward::Core::Diagnostics::Spot?]
53
+ # @rbs suggestion: String?
54
+ # @rbs return: String
55
+ def explain(message, spots, suggestion = nil)
56
+ hint = "Did you mean #{suggestion}?" if suggestion
57
+ [[message, Skyward::Core::Diagnostics::Excerpt.render(spots.compact)].compact.join("\n\n"), hint].compact.join("\n")
58
+ end
59
+
60
+ # @rbs problems: Array[String]
61
+ # @rbs return: String
62
+ def join(problems) = problems.join(problems.any? { |problem| problem.include?("\n") } ? "\n\n" : "\n")
63
+ end
@@ -20,10 +20,19 @@ module Skyward::ORM::Tables::Validation
20
20
  unknown = named.reject { |_, column| schema.columns.include?(column) }.uniq
21
21
  return if unknown.empty?
22
22
 
23
+ columns = schema.columns.map(&:to_s)
23
24
  problems = unknown.map do |declaration, column|
24
- "#{klass} has no column #{column}, which its #{declaration} names. " \
25
- "Add `attr_reader :#{column}`, or fix the name."
25
+ message = "#{klass} has no column #{column}, which its #{declaration} names. " \
26
+ "Add `attr_reader :#{column}`, or fix the name."
27
+ # A column declared nowhere, as the default primary key is, has no line to point at.
28
+ if klass.declared_at(declaration, column)
29
+ spot = Skyward::ORM::Tables::Sources.declaration(klass, declaration, column)
30
+ suggestion = Skyward::Core::Diagnostics::Suggestion.closest(column.to_s, columns)
31
+ Skyward::ORM::Tables::Sources.explain(message, [spot], suggestion)
32
+ else
33
+ message
34
+ end
26
35
  end
27
- raise Skyward::Core::BootError, problems.join("\n")
36
+ raise Skyward::Core::BootError, Skyward::ORM::Tables::Sources.join(problems)
28
37
  end
29
38
  end