skyward-orm 0.1.0 → 0.2.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.
- checksums.yaml +4 -4
- data/README.md +18 -14
- data/lib/skyward/orm/version.rb +5 -1
- data/lib/skyward/orm.rb +2 -0
- metadata +3 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: c65065a6d2f559ecea6fb3f0842bfaa2759372e1ba7112e23518f8742dda2fc5
|
|
4
|
+
data.tar.gz: 56fecc63feb4be7e7232475157c5ec51505a4d03acfe58774de24eb5f80dac4c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 7583828cd595bd8d0be5f0616fb084c730ce0562825a1dff59fcd8f11828b510c8439bce211358f6811bf7ed7c766b3b98fdf0c69cab29e83e8a72cd7ded3d3f
|
|
7
|
+
data.tar.gz: a38739f4b1689f20950a5ba8f64b81d13aeb55ef0c2df694184b21da1e997973358de16b881f8f731bb70e21a25cc29a6f5dd688419662330f7e906ebf5f7e1c
|
data/README.md
CHANGED
|
@@ -13,7 +13,7 @@ Skyward ORM is half of Skyward. The other half is [Skyward API](../skyward-api/R
|
|
|
13
13
|
# rbs_inline: enabled
|
|
14
14
|
require "skyward/orm"
|
|
15
15
|
|
|
16
|
-
class Todo < Skyward::Record
|
|
16
|
+
class Todo < Skyward::ORM::Record
|
|
17
17
|
table :todos
|
|
18
18
|
default done: false
|
|
19
19
|
|
|
@@ -77,12 +77,12 @@ Skyward ORM supports every Ruby that isn't end-of-life (3.3 and later, as of Nov
|
|
|
77
77
|
|
|
78
78
|
## Tables
|
|
79
79
|
|
|
80
|
-
A table is a plain Ruby class that subclasses `Skyward::Record`. Each `attr_reader` is a column, and its `#:` comment is the column's type. In an app organised by domain, name it after what it is: `Todos::Record`, `Lists::Record`.
|
|
80
|
+
A table is a plain Ruby class that subclasses `Skyward::ORM::Record`. Each `attr_reader` is a column, and its `#:` comment is the column's type. In an app organised by domain, name it after what it is: `Todos::Record`, `Lists::Record`.
|
|
81
81
|
|
|
82
82
|
```ruby
|
|
83
83
|
# rbs_inline: enabled
|
|
84
84
|
|
|
85
|
-
class Todo < Skyward::Record
|
|
85
|
+
class Todo < Skyward::ORM::Record
|
|
86
86
|
table :todos
|
|
87
87
|
references :list_id, List, on_delete: :cascade
|
|
88
88
|
default priority: :normal, done: false, created_at: Skyward.sql("now()")
|
|
@@ -186,7 +186,7 @@ Like ActiveRecord, Skyward ORM keeps the connection for you, so `Todo.where(...)
|
|
|
186
186
|
When you connect, Skyward ORM compares every loaded table class with the live schema and refuses to start if they disagree:
|
|
187
187
|
|
|
188
188
|
```
|
|
189
|
-
Skyward::SchemaMismatch: Todo doesn't match the todos table
|
|
189
|
+
Skyward::ORM::SchemaMismatch: Todo doesn't match the todos table
|
|
190
190
|
|
|
191
191
|
notes todos has no column notes.
|
|
192
192
|
Run `skyward migrate`, or `skyward migration` if you haven't generated one.
|
|
@@ -234,12 +234,14 @@ Order and paging: `order(:title)`, `order(created_at: :desc)`, `limit(20)` and `
|
|
|
234
234
|
Skyward ORM has no scope DSL, because Ruby already has methods, and the class is the table:
|
|
235
235
|
|
|
236
236
|
```ruby
|
|
237
|
+
# @rbs use Skyward::ORM::*
|
|
238
|
+
|
|
237
239
|
class Todo
|
|
238
|
-
# @rbs return:
|
|
240
|
+
# @rbs return: Query[Todo]
|
|
239
241
|
def self.open = where(done: false).order(created_at: :desc)
|
|
240
242
|
|
|
241
243
|
# @rbs today: Date
|
|
242
|
-
# @rbs return:
|
|
244
|
+
# @rbs return: Query[Todo]
|
|
243
245
|
def self.overdue(today: Date.today) = open.where(due_on: ...today)
|
|
244
246
|
end
|
|
245
247
|
|
|
@@ -248,6 +250,8 @@ Todo.open.where(list_id: 3) # start from a scope, then narrow it
|
|
|
248
250
|
Todo.where(list_id: 3).merge(Todo.open) # or combine two queries with merge
|
|
249
251
|
```
|
|
250
252
|
|
|
253
|
+
A file that names Skyward ORM's types in its signatures starts with `# @rbs use Skyward::ORM::*`, so they can write `Query[Todo]` for `Skyward::ORM::Query[Todo]`.
|
|
254
|
+
|
|
251
255
|
### Seeing the SQL
|
|
252
256
|
|
|
253
257
|
Every query can show its SQL without running it:
|
|
@@ -338,7 +342,7 @@ Columns with a default (`id`, `done`, `created_at`) and nullable ones (`due_on`)
|
|
|
338
342
|
|
|
339
343
|
### When the database says no
|
|
340
344
|
|
|
341
|
-
A duplicate email or a missing parent row isn't exceptional. It's an outcome your code should handle. So the plain write methods return either the rows or a `Skyward::Violation`:
|
|
345
|
+
A duplicate email or a missing parent row isn't exceptional. It's an outcome your code should handle. So the plain write methods return either the rows or a `Skyward::ORM::Violation`:
|
|
342
346
|
|
|
343
347
|
```ruby
|
|
344
348
|
result = User.insert(email:)
|
|
@@ -350,9 +354,9 @@ end
|
|
|
350
354
|
|
|
351
355
|
Steep 2.1 can't type-check `case`/`in`, so typed code matches on the class with `case`/`when`, and on the violation's `kind`.
|
|
352
356
|
|
|
353
|
-
`Skyward::Violation` has `kind` (`:unique`, `:foreign_key`, `:not_null` or `:check`), `constraint`, `columns` and the database's `message`.
|
|
357
|
+
`Skyward::ORM::Violation` has `kind` (`:unique`, `:foreign_key`, `:not_null` or `:check`), `constraint`, `columns` and the database's `message`.
|
|
354
358
|
|
|
355
|
-
When a violation would mean a bug, use the bang version. It returns the rows or raises `Skyward::ViolationError`, the way `save` and `save!` work in ActiveRecord:
|
|
359
|
+
When a violation would mean a bug, use the bang version. It returns the rows or raises `Skyward::ORM::ViolationError`, the way `save` and `save!` work in ActiveRecord:
|
|
356
360
|
|
|
357
361
|
```ruby
|
|
358
362
|
Todo.insert!(title: "Buy milk", list_id: 1) # => Todo
|
|
@@ -369,7 +373,7 @@ Skyward.transaction do
|
|
|
369
373
|
end
|
|
370
374
|
```
|
|
371
375
|
|
|
372
|
-
Every query inside the block runs in the transaction, and the block's value is returned. Skyward ORM rolls back if the block raises, **or if it returns a `Skyward::Violation`**, so the non-bang methods compose:
|
|
376
|
+
Every query inside the block runs in the transaction, and the block's value is returned. Skyward ORM rolls back if the block raises, **or if it returns a `Skyward::ORM::Violation`**, so the non-bang methods compose:
|
|
373
377
|
|
|
374
378
|
```ruby
|
|
375
379
|
result = Skyward.transaction do
|
|
@@ -391,11 +395,11 @@ Skyward ORM reads the same RBS as Steep, whether it's written inline or in `sig/
|
|
|
391
395
|
|
|
392
396
|
| When | What's checked |
|
|
393
397
|
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
394
|
-
| **As you type (Steep)** | The row type of every query. `Todo.where(...)` is a `Skyward::Query[Todo]`, `.to_a` is an `Array[Todo]`, `.into(TodoTitle)` is a `Query[TodoTitle]`, and `insert` returns `Todo \| Skyward::Violation`. No annotations are needed. |
|
|
398
|
+
| **As you type (Steep)** | The row type of every query. `Todo.where(...)` is a `Skyward::ORM::Query[Todo]`, `.to_a` is an `Array[Todo]`, `.into(TodoTitle)` is a `Query[TodoTitle]`, and `insert` returns `Todo \| Skyward::ORM::Violation`. No annotations are needed. |
|
|
395
399
|
| **When you generate a migration** | Column types, nullability and enum values all come from your types. |
|
|
396
400
|
| **At connect** | Every table class against the live schema, which catches migrations you haven't run. |
|
|
397
401
|
| **When a query is built** | Column names exist, and values match their column's type. `where(dnoe: false)` and `where(done: "yes")` both raise immediately, so your first test run catches them. |
|
|
398
|
-
| **In the database** | Constraints, which come back as `Skyward::Violation` values. |
|
|
402
|
+
| **In the database** | Constraints, which come back as `Skyward::ORM::Violation` values. |
|
|
399
403
|
|
|
400
404
|
Types are what Skyward ORM generates migrations from. Leave them off and queries still work, rows still come back as instances of your class, holding whatever values the driver returns, and you write the SQL for those columns yourself.
|
|
401
405
|
|
|
@@ -431,7 +435,7 @@ Skyward.migrate("db/migrate") # runs any migration the test database hasn't had
|
|
|
431
435
|
|
|
432
436
|
```ruby
|
|
433
437
|
describe Todo do
|
|
434
|
-
include Skyward::Transactional # each test runs in a transaction that's rolled back afterwards
|
|
438
|
+
include Skyward::ORM::Transactional # each test runs in a transaction that's rolled back afterwards
|
|
435
439
|
|
|
436
440
|
let(:list) { List.insert!(name: "Home") }
|
|
437
441
|
|
|
@@ -462,7 +466,7 @@ Rows are values, so assertions compare them directly with `==`.
|
|
|
462
466
|
|
|
463
467
|
## CLI
|
|
464
468
|
|
|
465
|
-
Skyward ORM and Skyward API share one `skyward` command. Each adds its own commands to it. The executable comes with Skyward Core, which every Skyward gem depends on. The ORM's commands live in `lib/skyward/orm/commands.rb`, which registers each with `Skyward::
|
|
469
|
+
Skyward ORM and Skyward API share one `skyward` command. Each adds its own commands to it. The executable comes with Skyward Core, which every Skyward gem depends on. The ORM's commands live in `lib/skyward/orm/commands.rb`, which registers each with `Skyward::Core::CLI.register`.
|
|
466
470
|
|
|
467
471
|
| Command | Does |
|
|
468
472
|
| ------------------------------------- | ----------------------------------------------------------------------------- |
|
data/lib/skyward/orm/version.rb
CHANGED
data/lib/skyward/orm.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: skyward-orm
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Jake Bottrall
|
|
@@ -15,14 +15,14 @@ dependencies:
|
|
|
15
15
|
requirements:
|
|
16
16
|
- - '='
|
|
17
17
|
- !ruby/object:Gem::Version
|
|
18
|
-
version: 0.
|
|
18
|
+
version: 0.2.0
|
|
19
19
|
type: :runtime
|
|
20
20
|
prerelease: false
|
|
21
21
|
version_requirements: !ruby/object:Gem::Requirement
|
|
22
22
|
requirements:
|
|
23
23
|
- - '='
|
|
24
24
|
- !ruby/object:Gem::Version
|
|
25
|
-
version: 0.
|
|
25
|
+
version: 0.2.0
|
|
26
26
|
- !ruby/object:Gem::Dependency
|
|
27
27
|
name: zeitwerk
|
|
28
28
|
requirement: !ruby/object:Gem::Requirement
|