From b4476096a16745a69908c80e5c040f60b4969ce7 Mon Sep 17 00:00:00 2001 From: Peter Schilling Date: Sun, 1 Sep 2024 07:34:24 -0700 Subject: [PATCH 1/2] chore: Update docs (#7) --- .github/workflows/deploy-pages.yml | 30 --------------- .github/workflows/main.yml | 2 +- .yardopts | 5 +++ Gemfile.lock | 2 + README.md | 59 +++++++++++++++++++----------- cool_id.gemspec | 3 +- sig/cool_id.rbs | 4 -- 7 files changed, 48 insertions(+), 57 deletions(-) delete mode 100644 .github/workflows/deploy-pages.yml create mode 100644 .yardopts delete mode 100644 sig/cool_id.rbs diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml deleted file mode 100644 index 4af52c5..0000000 --- a/.github/workflows/deploy-pages.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: Deploy to Pages - -on: - workflow_run: - workflows: ["Ruby and Pages"] - types: - - completed - branches: - - main - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main' }} - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 776b942..fdfcbe2 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -27,8 +27,8 @@ jobs: run: bundle exec rake docs: + if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest - needs: build steps: - uses: actions/checkout@v4 - name: Set up Ruby diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..bc406c0 --- /dev/null +++ b/.yardopts @@ -0,0 +1,5 @@ +--no-private +--markup=markdown +--readme=README.md +--title='cool_id api documentation' +'lib/**/*.rb' - '*.md' LICENSE diff --git a/Gemfile.lock b/Gemfile.lock index 48a42a4..d4ec272 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -103,6 +103,7 @@ GEM tzinfo (2.0.6) concurrent-ruby (~> 1.0) unicode-display_width (2.5.0) + webrick (1.8.1) yard (0.9.36) PLATFORMS @@ -115,6 +116,7 @@ DEPENDENCIES rspec (~> 3.0) sqlite3 (~> 1.4) standard (~> 1.3) + webrick yard (~> 0.9.28) BUNDLED WITH diff --git a/README.md b/README.md index 76bbb75..02fe75f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ gem for rails apps to generates string ids with a prefix, followed by a [nanoid](https://zelark.github.io/nano-id-cc/). similar to the ids you see in stripe's api. also able to lookup any record by id, similar to rails' globalid. there's an [introductory blog post](https://schpet.com/note/cool-id) explaining why i made this. +## usage + +### basic id generation + ```ruby class User < ActiveRecord::Base include CoolId::Model @@ -12,38 +16,33 @@ User.create!(name: "...").id # => "usr_vktd1b5v84lr" ``` -lookup any record by its id +### locate records ```ruby CoolId.locate("usr_vktd1b5v84lr") # => # ``` -and generate ids without creating a record +### generate ids + +e.g. for batch inserts or upserts ```ruby -# generate an id, e.g. for batch inserts or upserts User.generate_cool_id # => "usr_vktd1b5v84lr" ``` -you can use cool_id with a separate field, keeping the default primary key: +### parsing ids ```ruby -class Product < ActiveRecord::Base - include CoolId::Model - cool_id prefix: "prd", id_field: :public_id -end - -product = Product.create!(name: "Cool Product") -product.id # => 1 (or another integer) -product.public_id # => "prd_vktd1b5v84lr" +parsed = CoolId.parse("usr_vktd1b5v84lr") +# => # -# You can still use CoolId.locate with the public_id -CoolId.locate("prd_vktd1b5v84lr") # => # +parsed.model_class +# => User ``` -this approach allows you to keep your primary key as an auto-incrementing integer while still benefiting from CoolId's functionality. it's particularly useful when you want to expose a public identifier that's separate from your internal primary key. +### configuration options it takes parameters to change the alphabet or length @@ -67,16 +66,26 @@ CoolId.configure do |config| end ``` -parsing ids +#### using a different id field + +you can use cool_id with a separate field, keeping the default primary key: ```ruby -parsed = CoolId.parse("usr_vktd1b5v84lr") -# => # +class Product < ActiveRecord::Base + include CoolId::Model + cool_id prefix: "prd", id_field: :public_id +end -parsed.model_class -# => User +product = Product.create!(name: "Cool Product") +product.id # => 1 (or a uuid or whatever primary key you like) +product.public_id # => "prd_vktd1b5v84lr" + +# locate will find this +CoolId.locate("prd_vktd1b5v84lr") # => # ``` +this approach allows you to avoid exposing your primary keys, read David Bryant Copeland's [Create public-facing unique keys alongside your primary keys](https://naildrivin5.com/blog/2024/08/26/create-public-facing-unique-keys-alongside-your-primary-keys.html) to learn why you might want to do this. it also allows you to adopt cool_id more easily in a project that already has some data. + ## installation @@ -90,6 +99,13 @@ bundle add cool_id gem "cool_id" ``` +don't want to deal with a dependency? copy it into your project: + +``` +mkdir -p app/lib +curl https://raw.githubusercontent.com/schpet/cool_id/main/lib/cool_id.rb -o app/lib/cool_id.rb +``` + ### adding cool_id to a single model use string ids when creating a table @@ -109,6 +125,8 @@ class User < ActiveRecord::Base end ``` +note: if you prefer more traditional primary keys (like bigints or uuids) you can use the `id_field` on a different column. + ### using cool_id on all models you have drank the coolaid. setup rails to use string ids on all new generated migrations @@ -135,7 +153,6 @@ end if you use the graphql ruby node interface, you can implement [object identification](https://graphql-ruby.org/schema/object_identification) - ```ruby # app/graphql/app_schema.rb class AppSchema < GraphQL::Schema diff --git a/cool_id.gemspec b/cool_id.gemspec index d865087..3c482fa 100644 --- a/cool_id.gemspec +++ b/cool_id.gemspec @@ -19,7 +19,7 @@ Gem::Specification.new do |spec| spec.metadata["changelog_uri"] = "https://github.com/schpet/cool_id/blob/main/CHANGELOG.md" # Specify which files should be added to the gem when it is released. - spec.files = Dir.glob(%w[lib/**/*.rb *.md LICENSE]) + spec.files = Dir.glob(%w[lib/**/*.rb *.md LICENSE .yardopts]) spec.require_paths = ["lib"] spec.add_dependency "nanoid", "~> 2.0" @@ -30,5 +30,6 @@ Gem::Specification.new do |spec| spec.add_development_dependency "rspec", "~> 3.0" spec.add_development_dependency "standard", "~> 1.3" spec.add_development_dependency "yard", "~> 0.9.28" + spec.add_development_dependency "webrick" spec.add_development_dependency "sqlite3", "~> 1.4" end diff --git a/sig/cool_id.rbs b/sig/cool_id.rbs deleted file mode 100644 index f79ea7a..0000000 --- a/sig/cool_id.rbs +++ /dev/null @@ -1,4 +0,0 @@ -module CoolId - VERSION: String - # See the writing guide of rbs: https://github.com/ruby/rbs#guides -end From 3a30e7554a51d5fe15b6930d52e65273e86a469d Mon Sep 17 00:00:00 2001 From: Peter Schilling Date: Tue, 3 Sep 2024 12:45:14 -0700 Subject: [PATCH 2/2] chore: Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 02fe75f..f30ba9c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # cool id -gem for rails apps to generates string ids with a prefix, followed by a [nanoid](https://zelark.github.io/nano-id-cc/). similar to the ids you see in stripe's api. also able to lookup any record by id, similar to rails' globalid. there's an [introductory blog post](https://schpet.com/note/cool-id) explaining why i made this. +gem for rails apps to generate string ids with a prefix, followed by a [nanoid](https://zelark.github.io/nano-id-cc/). similar to the ids you see in stripe's api. also able to lookup any record by id, similar to rails' globalid. there's an [introductory blog post](https://schpet.com/note/cool-id) explaining why i made this. ## usage