{"id":13509702,"url":"https://github.com/joshrieken/plasm","last_synced_at":"2025-12-11T23:43:01.361Z","repository":{"id":57533954,"uuid":"49236115","full_name":"joshrieken/plasm","owner":"joshrieken","description":"Ecto's composable query multitool (.count, .random, .earliest, .latest, .find, .at, .on, etc.)","archived":false,"fork":false,"pushed_at":"2020-06-09T17:39:57.000Z","size":106,"stargazers_count":90,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-01T09:35:06.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshrieken.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-07T23:02:38.000Z","updated_at":"2024-06-22T04:07:03.000Z","dependencies_parsed_at":"2022-09-26T18:21:22.407Z","dependency_job_id":null,"html_url":"https://github.com/joshrieken/plasm","commit_stats":null,"previous_names":["facto/plasm"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrieken%2Fplasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrieken%2Fplasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrieken%2Fplasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrieken%2Fplasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshrieken","download_url":"https://codeload.github.com/joshrieken/plasm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246324285,"owners_count":20759105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:01:11.730Z","updated_at":"2025-10-21T15:34:25.433Z","avatar_url":"https://github.com/joshrieken.png","language":"Elixir","funding_links":[],"categories":["Utilities"],"sub_categories":[],"readme":"# Plasm\n\n[![Build Status](https://travis-ci.org/facto/plasm.svg?branch=master)](https://travis-ci.org/facto/plasm)\n[![Deps Status](https://beta.hexfaktor.org/badge/all/github/facto/plasm.svg)](https://beta.hexfaktor.org/github/facto/plasm)\n[![Inline docs](http://inch-ci.org/github/facto/plasm.svg)](http://inch-ci.org/github/facto/plasm)\n\nA generic [composable query](http://blog.drewolson.org/composable-queries-ecto/) library for [Ecto](https://github.com/elixir-lang/ecto).\n\n:heart::heart::heart: Ecto, :cry::cry::cry: because I have to implement my own composable query functions for things like counting records, getting a random record and whatnot in all my models/projects.\n\nNO MORE.\n\nPlasm provides a set of generic, composable, higher-level functions that make working with Ecto more joyful and productive.\n\n\n## Design Objectives\n\n- [X] Work alongside `Ecto.Query` so both can be `import`ed without conflict\n- [X] Avoid reimplementing basic `Ecto.Query` functionality where possible\n- [X] Provide syntactic sugar for common queries (e.g., see `count` and `distinct_by`)\n- [X] Easy integration with Phoenix\n- [X] Permissive API (e.g., most functions that accept an atom will alternatively accept a string)\n\n\n## Examples\n\nInstead of writing this in your model:\n\n``` elixir\ndefmodule MyGhostBustingApp.ProtonPack\n  ...\n\n  def count(query) do\n    for q in query,\n    select: count(q.id)\n  end\n\n  ...\nend\n```\n\nAnd using it this way:\n\n``` elixir\nProtonPack |\u003e ProtonPack.count |\u003e Repo.one\n```\n\nJust use Plasm:\n\n``` elixir\nProtonPack |\u003e Plasm.count |\u003e Repo.one\n```\n\nMore examples:\n\n``` elixir\nPkeMeter |\u003e Plasm.later_than(:updated_at, \"2016-01-04T14:00:00Z\") |\u003e Repo.all\n```\n\n``` elixir\nGhostTrap |\u003e Plasm.find([3,6,9]) |\u003e Repo.all\n```\n\n``` elixir\nStayPuftMarshmallowMan |\u003e Plasm.random |\u003e Repo.one\n```\n\n## Using in Models\n\nYou can import Plasm and use it directly in your models:\n\n``` elixir\ndefmodule MyApp.SomeModel do\n  import Ecto.Query\n  import Plasm\n\n  ...\n\n  def random_distinct_names_by_order_of_insertion(query, n) do\n    query\n    |\u003e order_by(asc: :inserted_at)\n    |\u003e distinct_by(:name)\n    |\u003e random(n)\n  end\nend\n```\n\n\n## Using with Phoenix\n\nIf you want Plasm to be universally accessible in all your Phoenix models, you can add it to `web.ex`:\n\n``` elixir\ndefmodule MyApp.Web do\n  ...\n\n  def model do\n    quote do\n      ...\n\n      import Plasm\n    end\n  end\nend\n```\n\n\n## API\n\n``` elixir\nPlasm.at(query, field_name, ecto_date_time)\nPlasm.at_or_later_than(query, field_name, ecto_date_time)\nPlasm.at_or_earlier_than(query, field_name, ecto_date_time)\nPlasm.average(query, field_name)\nPlasm.count(query)\nPlasm.count_distinct(query, field_name)\nPlasm.distinct_by(query, field_name)\nPlasm.earlier_than(query, field_name, ecto_date_or_date_time)\nPlasm.earliest(query, field_name)\nPlasm.earliest(query, field_name, n)\nPlasm.find(query, primary_key)\nPlasm.find(query, primary_keys)\nPlasm.later_than(query, field_name, ecto_date_or_date_time)\nPlasm.latest(query, field_name)\nPlasm.latest(query, field_name, n)\nPlasm.maximum(query, field_name)\nPlasm.minimum(query, field_name)\nPlasm.on(query, field_name, ecto_date)\nPlasm.on_or_later_than(query, field_name, ecto_date)\nPlasm.on_or_earlier_than(query, field_name, ecto_date)\nPlasm.random(query)\nPlasm.random(query, n)\nPlasm.total(query, field_name)\nPlasm.where_all(query, field_names_and_values)\nPlasm.where_none(query, field_names_and_values)\n```\n\n### Why not use shorter names, like `avg`, `sum`, etc.?\n\nTo avoid conflicts when `import`ing. For instance, `Plasm.min\\2` and `Plasm.max\\2` would conflict with `Kernel.min\\2` and `Kernel.max\\2`, so if you're importing them, you'd need to prefix your calls with `__MODULE__`; e.g., `__MODULE__.min(query, field_name)`. This sucks, so I chose to go with the longer versions and tried to stay consistent.\n\n\n## Note On DB Support\n\nGuaranteed to work with Postgres; others might work but haven't been tested.\n\n\n## Note On Query Syntaxes\n\nEcto supports two query syntaxes, **keyword** and **query expression**.\n\nExample of the **keyword** syntax:\n\n``` elixir\ndef for_name_or_age(query, name, age) do\n  for x in query,\n  where: x.name == ^name or x.age == ^age\nend\n```\n\nExample of the **query expression** syntax:\n\n``` elixir\ndef for_name_or_age(query, name, age) do\n  query\n  |\u003e where([x], x.name == ^name or x.age == ^age)\nend\n```\n\nThe keyword syntax is a bit easier on the eyes, but is not fully compatible with Plasm. A case can be made for sticking with the query expression syntax for all functions that are meant to be composable, and especially if you plan to use Plasm or something like it.\n\n\n## Inspiration\n\nMany thanks to [Drew Olson](https://github.com/drewolson) for his [talk at ElixirConf 2015](https://www.youtube.com/watch?v=g84TDHt9MDc) and [insightful blog post](http://blog.drewolson.org/composable-queries-ecto/) on the subject of composable Ecto queries.\n\nAlso thanks to [Henrik Nyh](https://github.com/henrik) for his [Ectoo](https://github.com/henrik/ectoo) project, which has similar aims.\n\n\n## TODO:\n\n- [x] Tests\n- [x] Hex docs\n\n\n## Installation\n\nAdd Plasm to your list of dependencies in `mix.exs`:\n\n``` elixir\ndef deps do\n  [{:plasm, \"~\u003e 2.0\"}]\nend\n```\n\nEnsure Plasm is started before your application:\n\n``` elixir\ndef application do\n  [\n    applications: [\n      ...\n      :plasm\n      ...\n    ]\n  ]\nend\n```\n\nIf you want to be on the bleeding edge, track the `master` branch of this repo:\n\n``` elixir\n{:plasm, git: \"https://github.com/facto/plasm.git\", branch: \"master\"}\n```\n\n\n## Copyright and License\n\nCopyright (c) 2016-2020 Joshua Rieken.\n\nPlasm source code is licensed under the Apache 2 License (see LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrieken%2Fplasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshrieken%2Fplasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrieken%2Fplasm/lists"}