{"id":15957195,"url":"https://github.com/mamantoha/countdown-crystal","last_synced_at":"2025-07-14T15:09:00.514Z","repository":{"id":253133844,"uuid":"842576833","full_name":"mamantoha/countdown-crystal","owner":"mamantoha","description":"A simple Crystal library for calculating and producing an accurate, intuitive description of the timespan between two Time instances.","archived":false,"fork":false,"pushed_at":"2024-12-09T12:13:25.000Z","size":20,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T09:35:10.082Z","etag":null,"topics":["countdown-timer","crystal","time"],"latest_commit_sha":null,"homepage":"","language":"Crystal","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/mamantoha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-14T16:22:53.000Z","updated_at":"2025-02-22T05:35:43.000Z","dependencies_parsed_at":"2024-08-25T11:27:12.364Z","dependency_job_id":"fb03e172-da26-4bec-8e66-ff56ae3ad00a","html_url":"https://github.com/mamantoha/countdown-crystal","commit_stats":null,"previous_names":["mamantoha/countdown-crystal"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mamantoha/countdown-crystal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Fcountdown-crystal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Fcountdown-crystal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Fcountdown-crystal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Fcountdown-crystal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mamantoha","download_url":"https://codeload.github.com/mamantoha/countdown-crystal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Fcountdown-crystal/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265311872,"owners_count":23745161,"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":["countdown-timer","crystal","time"],"created_at":"2024-10-07T13:40:47.948Z","updated_at":"2025-07-14T15:09:00.488Z","avatar_url":"https://github.com/mamantoha.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Countdown\n\n[![Crystal CI](https://github.com/mamantoha/countdown-crystal/actions/workflows/crystal.yml/badge.svg?branch=main)](https://github.com/mamantoha/countdown-crystal/actions/workflows/crystal.yml)\n[![GitHub release](https://img.shields.io/github/release/mamantoha/countdown-crystal.svg)](https://github.com/mamantoha/countdown-crystal/releases)\n[![License](https://img.shields.io/github/license/mamantoha/countdown-crystal.svg)](https://github.com/mamantoha/countdown-crystal/blob/master/LICENSE)\n\nA simple Crystal library for calculating and producing an accurate, intuitive description of the timespan between two `Time` instances.\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n   ```yaml\n   dependencies:\n     countdown:\n       github: mamantoha/countdown-crystal\n   ```\n\n2. Run `shards install`\n\n## Features\n\n- Handles leap years, varying month lengths, timezone differences.\n- Generates human-readable strings representing the timespan.\n- Provides easy access to individual components (years, months, days, hours, minutes, seconds) of the timespan.\n\n## Usage\n\n```crystal\nrequire \"countdown\"\n\nstart_time = Time.local(2023, 12, 31, 23, 59)\nend_time = Time.local(2024, 2, 29, 12, 30)\n\ncountdown = Countdown.new(start_time, end_time)\nputs countdown.components  # =\u003e {years: 0, months: 1, days: 28, hours: 12, minutes: 31, seconds: 0}\nputs countdown.to_s        # =\u003e \"1 month, 28 days, 12 hours and 31 minutes\"\n```\n\n```crystal\nrequire \"countdown\"\n\nTime::Location.local = Time::Location.load(\"Europe/Kyiv\")\n\nstart_time = Time.local(2022, 3, 27, 2, 59)\n# =\u003e 2022-03-27 02:59:00.0 +02:00 Local\n\nend_time = Time.local(2022, 3, 28, 3, 0)\n# =\u003e 2022-03-28 03:00:00.0 +03:00 Local\n\ncountdown = Countdown.new(start_time, end_time)\n\ncountdown.components\n# =\u003e {years: 0, months: 0, days: 1, hours: 1, minutes: 1, seconds: 0}\n\ncountdown.to_s\n# =\u003e \"1 day, 1 hour and 1 minute\"\n\ncountdown.to_s(oxford_comma: true)\n# =\u003e \"1 day, 1 hour, and 1 minute\"\n```\n\n## The Algorithm\n\nThe `Countdown` library calculates the difference between two dates in a way that feels natural and consistent. It treats \"a month from now\" as \"the same date next month,\" ensuring smooth, predictable countdowns without sudden jumps.\n\nThe library works like basic subtraction, adjusting for time units (seconds, minutes, hours, days, months, years) as needed. Since months have different numbers of days, `Countdown` carefully tracks each month to provide accurate results.\n\n## Time Zones \u0026 Daylight Saving Time\n\n`Countdown` also handles time zone differences and daylight saving time changes, ensuring that your countdowns are accurate regardless of the time zone or DST shifts between the start and end dates.\n\n## Inspiration\n\nThis library was inspired by Countdown.js. While the idea was taken from [Countdown.js](https://countdownjs.org/), no code was reused, and this implementation was developed entirely from scratch.\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/mamantoha/countdown-crystal/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Contributors\n\n- [Anton Maminov](https://github.com/mamantoha) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmamantoha%2Fcountdown-crystal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmamantoha%2Fcountdown-crystal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmamantoha%2Fcountdown-crystal/lists"}