{"id":13508857,"url":"https://github.com/lau/calecto","last_synced_at":"2026-02-22T14:43:14.242Z","repository":{"id":28061878,"uuid":"31558623","full_name":"lau/calecto","owner":"lau","description":"Adapter for the Calendar library in Ecto","archived":false,"fork":false,"pushed_at":"2021-01-27T20:38:14.000Z","size":154,"stargazers_count":148,"open_issues_count":5,"forks_count":21,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-12-13T01:50:18.093Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lau.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-02T19:29:36.000Z","updated_at":"2025-09-15T14:35:26.000Z","dependencies_parsed_at":"2022-08-02T13:06:09.181Z","dependency_job_id":null,"html_url":"https://github.com/lau/calecto","commit_stats":null,"previous_names":["lau/kalecto"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/lau/calecto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lau%2Fcalecto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lau%2Fcalecto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lau%2Fcalecto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lau%2Fcalecto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lau","download_url":"https://codeload.github.com/lau/calecto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lau%2Fcalecto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29701959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T23:35:04.139Z","status":"ssl_error","status_checked_at":"2026-02-21T23:35:03.832Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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:00:59.504Z","updated_at":"2026-02-22T14:43:14.165Z","avatar_url":"https://github.com/lau.png","language":"Elixir","funding_links":[],"categories":["ORM and Datamapping"],"sub_categories":[],"readme":"Calecto\n=======\n\n[![Build\nStatus](https://travis-ci.org/lau/calecto.svg?branch=master)](https://travis-ci.org/lau/calecto)\n[![Hex Version](http://img.shields.io/hexpm/v/calecto.svg?style=flat)](https://hex.pm/packages/calecto)\n\n\n## Library originally made for older Ecto versions\n\nThis was made before Ecto had native support for built in Elixir Calendar types.\nIf Ecto 2.1 and newer is used, Calecto should only be used for the `Calecto.DateTime`\ntype, which is meant for `DateTime`s that are not UTC only. This type is specific to Postgres.\nExcept for `Calecto.DateTime` the other types have equivalent built in types in Ecto 2.1.\n\n## Description\n\nLibrary to make it easy to use [Calendar](https://github.com/lau/calendar) and\n[Ecto](https://github.com/elixir-lang/ecto) together.\nFor saving dates, times and datetimes in Ecto. Instead of using the Ecto\ntypes for Date, Time and DateTime, you can access the features of the Calendar\nlibrary. With timezone awareness, parsing, and formatting functionality.\n\nFor use with Elixir 1.3+ and Ecto 2.1+ add the following version to your deps:\n\n```elixir\ndefp deps do\n  [ {:calecto, \"~\u003e 0.17.0\"}, ]\nend\n```\n\nIf you use a Calendar version earlier than 0.16, use Calecto version ~\u003e 0.6.1\nIf you use an Ecto version earlier than 2.1, use Calecto version ~\u003e 0.16.0\n\n## Super quick way to get started\n\nHere's how to display `inserted_at` and `updated_at` dates using the\nfunctionality of the Calendar library:\n\n- Add :calecto to your deps in your mix.exs file (see above) and run `mix deps.get`\n\n### If you are using Phoenix\n\n- If you are using Phoenix you can add the line `use Calecto.Schema` in the file\n`web/web.ex` in the `model` function definition like so:\n\n```elixir\ndef model do\n  quote do\n    use Ecto.Schema\n    use Calecto.Schema, usec: true\n\n    # ...\n  end\nend\n```\n\n### If you are not using Phoenix\n\n- An alternative method to adding the line in `web/web.ex` is the following:\n  In your Ecto models, where you have a schema definition with a `timestamps`\n  line, under the line that says `use Ecto.Schema` add `use Calecto.Schema` like so:\n\n```elixir\ndefmodule Weather do\n  use Ecto.Schema\n  use Calecto.Schema, usec: true\n\n  schema \"weather\" do\n    field :city, :string\n    timestamps\n  end\nend\n```\n\n### Formatting timestamps\n\nThis means that your timestamps will be loaded as `DateTime` structs\ninstead of Ecto.DateTime structs. You can use the formatting functionality\nin Calendar.\n\n- Format an `inserted_at` timestamp using Calendar:\n\n```elixir\n@post.inserted_at |\u003e Calendar.Strftime.strftime!(\"%A, %e %B %Y\")\n```\nIt will return for instance: `Monday, 9 March 2015`\n\nThere are other formatting functions. For instance: http timestamp, unix\ntimestamp, RFC 3339 (ISO 8601). You can also shift the timestamp to another\ntimezone in order to display what date and time it was in that particular\ntimezone. See more in the [Calendar documentation](http://hexdocs.pm/calendar/).\n\n## The types\n\nIf you have a primitive type as listed below you can swap it for a Calecto type\nsimply by adding the type to your Ecto schema.\n\nExcept for `Calecto.DateTime` only use the types starting with `Calecto` with Ecto\nversion older than 2.1. For Ecto 2.1 and higher use the types that are built\ninto Ecto 2.1 - shown in the second column.\n\n| Primitive type            | Ecto 2.1+ schema type | Legacy Ecto schema type | Equivalent Calendar type |\n| ------------------------- | ----------------------| ----------------------- | ------------------------ |\n| *Used in migrations*      | *Used in schemas*     | *Used in schemas*       | *Type returned from db*  |\n| :date                     | :date                 | Calecto.Date            | Date                     |\n| :time                     | :time                 | Calecto.Time            | Time                     |\n| :utc_datetime             | :utc_datetime         | Calecto.DateTimeUTC     | DateTime                 |\n| :naive_datetime           | :naive_datetime       | Calecto.NaiveDateTime   | NaiveDateTime            |\n| :calendar_datetime        | Calecto.DateTime*     | Calecto.DateTime*       | DateTime                 |\n\nIf you have a `datetime` as a primitive type, you can use `Calecto.NaiveDateTime` or\n`Calecto.DateTimeUTC`.\nIf you have a `date` as a primitive type, you can use `Calecto.Date`.\nIf you have a `time` as a primitive type, you can use `Calecto.Time`.\n\nPut the primitive type in your migrations and the Ecto type in your schema.\n\n*) If you are using Postgres as a database you can also use the Calecto.DateTime\ntype. This allows you to save any Calendar.DateTime struct. This is useful for\nsaving for instance future times for meetings in a certain timezone. Even if\ntimezone rules change, the \"wall time\" will stay the same. See the\n\"DateTime with Postgres\" heading below.\n\n## Example usage\n\nIn your Ecto schema:\n\n```elixir\ndefmodule Weather do\n  use Ecto.Schema\n  use Calecto.Schema, usec: true\n\n  schema \"weather\" do\n    field :temperature,      :integer\n    field :nice_date,        Calecto.Date\n    field :nice_time,        Calecto.Time\n    field :nice_datetime,    Calecto.DateTimeUTC\n    field :another_datetime, Calecto.NaiveDateTime\n    timestamps usec: true\n    # the timestamps will be DateTimeUTC because of the `use Calecto.Schema` line\n  end\nend\n```\n\nIf you have a Calendar DateTime in the Etc/UTC timezone\nyou can save it in Ecto as a DateTimeUTC.\n\nLet's create a new DateTime to represent \"now\":\n\n```elixir\n    iex\u003e example_to_be_saved_in_db = DateTime.utc_now\n    %DateTime{calendar: Calendar.ISO, day: 30, hour: 15, microsecond: {46167, 6},\n    minute: 47, month: 6, second: 15, std_offset: 0, time_zone: \"Etc/UTC\",\n    utc_offset: 0, year: 2016, zone_abbr: \"UTC\"}\n```\n\nAnother way of getting a DateTime is parsing JavaScript style milliseconds:\n\n```elixir\n    iex\u003e parsed_datetime = Calendar.DateTime.Parse.js_ms!(\"1425314899000\")\n    %DateTime{calendar: Calendar.ISO, day: 2, hour: 16, microsecond: {0, 3},\n    minute: 48, month: 3, second: 19, std_offset: 0, time_zone: \"Etc/UTC\",\n    utc_offset: 0, year: 2015, zone_abbr: \"UTC\"}\n```\n\nSince the field `nice_datetime` is of the DateTimeUTC type, we can save\nCalendar.DateTime structs there if they are in the Etc/UTC timezone:\n\n```elixir\n    weather_struct_to_be_saved = %Weather{nice_datetime: parsed_datetime}\n```\n\nThe `DateTime` struct returned from the database can be used with\n`Calendar.DateTime` functions. We could for instance use the functions in\nCalendar to shift this UTC datetime to another time zone:\n\n```elixir\n    iex\u003e example_loaded_from_db |\u003e Calendar.DateTime.shift_zone!(\"Europe/Copenhagen\")\n    %DateTime{calendar: Calendar.ISO, day: 2, hour: 17, microsecond: {0, 3},\n    minute: 48, month: 3, second: 19, std_offset: 0, time_zone: \"Europe/Copenhagen\",\n    utc_offset: 3600, year: 2015, zone_abbr: \"CET\"}\n```\n\nOr we could get the unix timestamp:\n\n```elixir\n    iex\u003e example_loaded_from_db |\u003e Calendar.DateTime.Format.unix\n    1425314899\n```\n\nOr format it via strftime:\n\n```elixir\n    iex\u003e example_loaded_from_db |\u003e Calendar.Strftime.strftime!(\"The time is %T and it is %A.\")\n    \"The time is 16:48:19 and it is Monday.\"\n```\n\nThe are many more possiblities with Calendar for formatting, parsing etc. Look\nat the [Calendar documentation](http://hexdocs.pm/calendar/) for a detailed description.\n\n## DateTime with Postgres\n\nIf you are using Postgres, you can save and load DateTime structs that are not\nin the Etc/UTC timezone. This requires that a special type is added to the\ndatabase. By running the following command you can generate a migration that\nadds this type:\n\n```\n    mix calecto.add_type_migration\n```\n\nThen run the migration (`mix ecto.migrate`). This adds the `calendar_datetime`\ntype to the Postgres database. In migrations you can use `:calendar_datetime`.\n\nIn the schemas you can use the type `Calecto.DateTime` for fields that have\nbeen created with :calendar_datetime type in migrations.\n\n## Documentation\n\n[Documentation for Calecto is available at hexdocs.](http://hexdocs.pm/calecto/)\n\nMore information about Calendar functionality in the [Calendar documentation](http://hexdocs.pm/calendar/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flau%2Fcalecto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flau%2Fcalecto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flau%2Fcalecto/lists"}