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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0611e9bbfef973bdbcf47265afa0c0d5ba42e677c987eaeb9112028e244146ac
4
- data.tar.gz: fdd3b26d97b405b701bdfdd324ab503e8e7ee8c733a81161462a4bd578595e6c
3
+ metadata.gz: c65065a6d2f559ecea6fb3f0842bfaa2759372e1ba7112e23518f8742dda2fc5
4
+ data.tar.gz: 56fecc63feb4be7e7232475157c5ec51505a4d03acfe58774de24eb5f80dac4c
5
5
  SHA512:
6
- metadata.gz: edf1a82ea278503add84a869cfeaa9dc09e087a63b927eac2e376a7d5b9ecf9d6692b517e10f6beaa1b4c41efbcdb18e75febff3d241d63038642e0e95a21640
7
- data.tar.gz: 611b2c1d13fe60486b5bfe6e33bcf7a26bd1a8a1fefb6dddc94626690c982c9e887fba0bedd493d80fa0651951caee3747b7398f7b0a0679de155ed26f577341
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: Skyward::Query[Todo]
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: Skyward::Query[Todo]
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::Commands.register`.
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
  | ------------------------------------- | ----------------------------------------------------------------------------- |
@@ -2,6 +2,10 @@
2
2
 
3
3
  module Skyward
4
4
  module ORM
5
- VERSION = "0.1.0" #: String
5
+ # x-release-please-start-version
6
+
7
+ VERSION = "0.2.0" #: String
8
+
9
+ # x-release-please-end
6
10
  end
7
11
  end
data/lib/skyward/orm.rb CHANGED
@@ -6,4 +6,6 @@ require_relative "orm/version"
6
6
 
7
7
  loader = Zeitwerk::Loader.for_gem_extension(Skyward)
8
8
  loader.inflector.inflect("orm" => "ORM")
9
+ # The skyward executable loads it, and it defines no constant.
10
+ loader.ignore("#{__dir__}/orm/commands.rb")
9
11
  loader.setup
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.1.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.1.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.1.0
25
+ version: 0.2.0
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: zeitwerk
28
28
  requirement: !ruby/object:Gem::Requirement