romcal: Maintenance and bug fixes for new Typescript codebase

Shalom @emagnier and @tukusejssirs!

Here’s a list of issues that I suggest we look into (in no particular order) before the _F-TypeScript branch is merged to dev:

  • Revise locale management to make it behave as here in master. Keep output messages in the console but downgrade error messages to warnings.
  • Revise variable names (especially type declarations) to be more consistent and meaningful
  • Add more tsdoc compliant comments to code to improve quality of API documentation
  • Fix known issues with TS code as described here
  • Cleanup folder structure and file naming conventions
  • Cleanup README.md
  • Cleanup of romcal consumer facing response (#180).
  • Consistency of configuration options (#163)

Suggestions to make this list achievable and this issue “close-able” in a reasonable amount of time:

  1. Let’s keep the list concise and targeted mostly to bug fixes.
  2. If there’s a need for new features to be listed here, they should be for better usability of existing features (i.e. #180). New functionality and features should be done at another time.
  3. Lets keep this issue list short and sweet and link to extended discussion in other issues.

Considerations:

  • I started transforming some of the comments in the codebase to be tsdoc compliant. However, it is far from completion. Better tsdoc compliant comments in our code = better API documentation for our consumers.

Let me know your thoughts!

About this issue

  • Original URL
  • State: closed
  • Created 7 years ago
  • Comments: 25 (10 by maintainers)

Commits related to this issue

Most upvoted comments

Hello @pejulian, I’m reply to your message written here https://github.com/romcal/romcal/pull/189#issuecomment-620936919.

I also agree for an interim release of the TS work, at least into the dev branch for a first step. After that we could reevaluate the way to a master release. And I agree with you to focus on critical bugs. This should also include the build system, so everyone can work, contribute and also debug the codebase for all their needs.

I wanted to give more time to contribute to this, especially the build, but I’m still very busy on other projects currently. However, as I needed romcal’s new features quickly for my projects, I was able to implement most of them on a private fork (but still sticked on JS). This gave me the possibility to test and challenge quickly their use cases for real needs. I would like to port them progressively to TS on this repo, especially as I now use almost exclusively TS for all my web projects.

Thank you @pejulian for your message. It’s same here in Paris, almost everything is suspended, and we are just at the beginning of all of that in Europe. Thanks to you two for your prayers, let’s stay together in prayer fellowship.

And also thank you for your time on the build system for romcal and all the TS improvement. No worry for your silence, we are all well busy. I didn’t had yet luck to invest more time on it, and learn more about tsconfig and webpack for both browser and Node usages, so all your hard work is precious. I’m following with a great interest all the moves on the TS branch!

@pejulian, same here in Slovakia (no Masses at least for two weeks). I pray for you @romcal/romcal-contributors, two!

Hi @emagnier

Pardon my silence for the past few days.

I had a bit of a learning curve with getting tsconfig path aliases to work with webpack, jest and finally the typings output in dist. It was indeed a struggle but it was not in vain. Finally, with the appropriate tooling, I believe I have a workable solution for us all. Now, we should be able to import and use constructs from romcal as needed. Note however that the import syntax is slightly different.

In the main entry point, I have made one default export called Romcal followed by a ton of other named exports for advanced usage. Romcal remains the main entry point class, containing the 2 main static methods calendarFor and queryFor that returns the standard output of the library. Therefore, a possible usage scenario in a consuming ES6 or TS application could look something like this:

import Romcal, { DateItem, advent, LITURGICAL_COLORS, LiturgicalColor, LiturgicalColorKeys, ChristmastideEndings } from 'romcal';

I tested this out on a typescript react application that I am working on now (romcal-app). I was able to import the functions I needed and get typings and tsdoc metadata for them.

npm install romcal@canary to give it a go and let me know your thoughts.

PS:- I pray that you, @tukusejssirs and everyone else who’s been a part of romcal is taking good care of yourselves in light of the corona virus outbreak in Europe. It’s also a big concern here in Malaysia where I am. Masses and other gatherings in all archdioceses have been temporarily suspended until the situation improves. Let us keep each other in prayer in these troubling times.

Also: I am working on separation of multiple celebrations occuring on a day, so that should be added to the TODO list, too.

Is there an issue you could link me to for more information about this?

It’s now possible to get multiple optional memories falling on a specific day (in addition to the feria). Support for that has been added in #162 (and the original issue: #12).

@tukusejssirs yes I know this project. It’s another good one, with a different approach and technologies 👍

I don’t know why you say it seems to be unmaintained, since it seems maintained to me. Also, note that the project that you linked to mostly just provides an API for the functionality of this project by the same author.

FYI I’ve added a few commits to the TS branch.

  • We can now debug romcal directly from the TS code. Basically, we can import romcal into a test file (with the desired romcal options), and run/debug all the codebase from there. For example node romcal-debug.ts -r ts-node/register -r tsconfig-paths/register, or directly from an IDE like WebStorm or VSCode.
  • But I had to back off the lodash-es modules. This was causing some issues when running and debugging the source code without webpack. For the time being we are back to the traditional lodash dependency. The frontend library generated by webpack has now ~200KiB more, so we should pay some attention again on the lodash library and find a solution for all cases.
  • I also split the tsconfig.json in 2 files. The default tsconfig.json contain the settings to run or debug the codebase. IDEs or tools like ts-node generally lean on the default tsconfig.json. Then I created a tsconfig.build.json that inherit from the default one, for all webpack tasks. There are still 2 other existing tsconfig, one for jest and another one for webpack, we may try to include them in the 2 others, to not have too many config files.
  • @pejulian if you don’t mind I have renamed and simplified a bit the path aliases. I find having the paths or directories lowercase (between @ and / chars) easiest to read, and be closest to the codebase structure. Let me know if it bothers you.
  • I’ve renamed the public DateItem object to RomcalDateItem, so when playing with the RomcalDateItem objects outside the romcal codebase, this object remain identified to romcal.

And more to come, hopefully soon.

@pejulian I thought I was able to debug the main TS codebase, but in fact I was simply running the dist files. Do you have any special config locally to be able to run/debug the main codebase? By default I’m still getting the Cannot use import statement outside a module, but I was able to fix it by editing the tsconfig.json. Then I get the Cannot find module '@RomcalModels/romcal-date-item'. I spent hours making it work, playing with paths in the tsconfig.json and package.json files, but finally made a quick fix by specifying relative paths. But after all of that, I’m still stuck on the SyntaxError: Cannot use import statement outside a module again. I tried to run/debug with ts-node, VSCode and Webstorm.

However I’m able to run the webpack build. So I might miss something. If you have any tricks, it will be more than welcome. I’m afraid I will not be able to spend more time on that branch, I’m also busy on some other projects that also need to move forward.

And in the meantime, I’m continuing to work on the previous romcal version, but I really hope to get on board the new TS codebase, and to port my work on it.

Hi @emagnier,

After running further tests on my machine, I realised that only the default export of romcal, which is named Romcal is “import”-able by the end user. When importing some other construct (i.e. Seasons), the typings to source doesn’t work correctly therefore resulting in the errors you see. I am guessing this has something to do with the combination of settings I used in tsconfig.json and webpack itself. I will look into the issue and see how it can be fixed.

@tukusejssirs: There is some good ideas and most of them are already exposed in different issues. But here it’s about releasing the TS branch, or eventually review the usage of existing features. Not about adding new features (we will not do everything in one release). So we should try to stay on the scope of this topic. Otherwise it will be hard to keep track on things and keep the issue tracker organised.

Regarding the documentation, what do you think to use .md files in the codebase, instead of the wiki. Indeed, the readme.md should be lightened and give only concise information. But having the rest of the documentation (in a /doc/**/*.md) would allow having versioning on the documentation (to be able to get the documentation for a specific romcal version). In addition, .md files will be easy to wrap up in a future romcal website that could include the documentation.

However wiki could still be a first step to help us writing and organise all the documentation.

On the README.md and the docs: #61 and #57.

Don’t forget #163 please! 😃

Added to the list! 😄

What do you think about my suggestion on the division of the l10n files into multiple files (for more info see this comment)?

The suggestion definitely has merit, but I’d vote to implement it as a new feature in a future milestone as there is some technical impact to the how stuff works now.

Don’t we wanna move the documentation to GitHub Wiki?

Indeed, you are right:- we should move all the lengthy details to the Wiki and leave only important information in the main README.md file. I’ve renamed the item in the list to “Cleanup README.md” instead.

Anyway: don’t you think that all these changes break the API in comparison with v1.3.0? If the answer is yes, we should move this issue to %romcal v2.0.0.

Yes, there are breaking changes on the way:- a major release definitely makes more sense. My mistake, I’ll reassign the milestone.

Also: I am working on separation of multiple celebrations occuring on a day, so that should be added to the TODO list, too.

Is there an issue you could link me to for more information about this?