From 0c9b2cf5c8e2f5bbef89a1d6770312c92507b25e Mon Sep 17 00:00:00 2001 From: Priyadi Iman Nurcahyo <1102197+priyadi@users.noreply.github.com> Date: Mon, 22 Jul 2024 20:21:45 +0700 Subject: [PATCH] docs: update readme (#130) --- CHANGELOG.md | 4 ++ README.md | 75 ++++++++++++++++++++++-- packages/collections-common/README.md | 15 +++-- packages/collections-contracts/README.md | 25 ++++++-- packages/collections-orm/README.md | 22 +++++-- 5 files changed, 125 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 19245d7..9e5aacd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## 0.10.1 + +* docs: update readme + ## 0.10.0 * fix(orm): `getQueryBuilder()` now clones the query builder diff --git a/README.md b/README.md index 35a57d8..4da98d0 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,78 @@ -# Rekalogika Collections +# rekalogika/collections -TBD +Pragmatic, opinionated enhancements to Doctrine's Collections library. Improves +the use of Doctrine Collections in large datasets, and other common problems. + +Full documentation: [rekalogika.dev/collections](https://rekalogika.dev/collections) + +## Background + +We work with huge datasets that are managed by Doctrine ORM, and have complex +business rules. These come with these challenges: + +* With standard Doctrine, it seems it is too easy to introduce bugs that will + accidentally load the entire dataset into memory and cause out-of-memory + errors. And these sorts of errors will usually only show up in production, but + never in the development environment. + +* Iterating over large datasets with the correct method is difficult and + cumbersome. You usually need to devise custom solutions for each use case. + +* Counting the number of records is very slow. Sometimes we can do away with the + count, sometimes it is a must, and we need to work around the problem. + +Other, non-performance issues include: + +* Doctrine's `Selectable` appears to be a prevalent source of abstraction leak. + Coders tend to litter the codebase with internal-dependent `Criteria` objects, + and updating the entity can potentially become a nightmare. No static analysis + tool can currently detect this problem. In fact, some exacerbate the problem + by assuming a `Collection` must also be a `Selectable`. + +Previously, we created `rekalogika/doctrine-collections-decorator` to solve +these problems. However, it is still too cumbersome because we need to approach +the problem one at a time. We need a more comprehensive solution that applies +to most, if not all, of our use cases. + +## Components + +* Decorator classes that enhance any Doctrine Collections classes. +* Query-backed collections. Turns a `QueryBuilder` into a lazy-loading + collection. +* An alternative implementation of the repository pattern that implements + `Collection`. +* Modifications to `ArrayCollection` that does `matching()` against the private + properties directly, to reproduce the same behavior of `PersistentCollection`. + +## Features + +* Safeguards against potential out-of-memory situations. Throws an exception + before it hits harder-to-debug out-of-memory situation. +* Pluggable counting strategies. Work around long counting times using your own + counting strategies. +* Full versions of the collection classes that offer full compatibility with the + original Doctrine Collection. And the minimal flavors that only expose the + safe methods. +* Built in keyset pagination using + [`rekalogika/rekapager`](https://rekalogika.dev/rekapager) library. Iterate + over collections of any size without loading them all into memory. And without + having to create ad-hoc queries every time you need to achieve that. +* Keyset pagination can also be used to create pagination for user interfaces + and API outputs. +* Encourages you to create expressive, higher-level methods to provide the same + functionality as the `Selectable` interface, but without exposing the inner + workings of the class. ## Documentation -TBD +[rekalogika.dev/collections](https://rekalogika.dev/collections) ## License -MIT \ No newline at end of file +MIT + +## Contributing + +This library consists of multiple repositories split from a monorepo. Be sure to +submit issues and pull requests to the +[rekalogika/collections](https://github.com/rekalogika/collections) monorepo. \ No newline at end of file diff --git a/packages/collections-common/README.md b/packages/collections-common/README.md index 8d014a7..c525a0c 100644 --- a/packages/collections-common/README.md +++ b/packages/collections-common/README.md @@ -1,11 +1,18 @@ -# Rekalogika Collections Domain +# rekalogika/collections-common -TBD +Common library required by other components of the `rekalogika/collections` +library. ## Documentation -TBD +[rekalogika.dev/collections](https://rekalogika.dev/collections) ## License -MIT \ No newline at end of file +MIT + +## Contributing + +This library consists of multiple repositories split from a monorepo. Be sure to +submit issues and pull requests to the +[rekalogika/collections](https://github.com/rekalogika/collections) monorepo. \ No newline at end of file diff --git a/packages/collections-contracts/README.md b/packages/collections-contracts/README.md index 8d014a7..e5aca51 100644 --- a/packages/collections-contracts/README.md +++ b/packages/collections-contracts/README.md @@ -1,11 +1,28 @@ -# Rekalogika Collections Domain +# rekalogika/collections-domain -TBD +Transforms a Doctrine `Collection` object into our `Recollection` object, which +extends `Collection` itself but also extends `PageableInterface` from our +`rekalogika/rekapager` library. + +The features include: + +* Safeguards against potential out-of-memory situations. +* Pluggable counting strategies. +* Keyset pagination for batch processing and user interfaces. + +The classes also available in the minimal flavor, which only exposes the safe +methods, those which won't trigger full load of an extra-lazy collection. ## Documentation -TBD +[rekalogika.dev/collections](https://rekalogika.dev/collections) ## License -MIT \ No newline at end of file +MIT + +## Contributing + +This library consists of multiple repositories split from a monorepo. Be sure to +submit issues and pull requests to the +[rekalogika/collections](https://github.com/rekalogika/collections) monorepo. \ No newline at end of file diff --git a/packages/collections-orm/README.md b/packages/collections-orm/README.md index 8d014a7..07462b9 100644 --- a/packages/collections-orm/README.md +++ b/packages/collections-orm/README.md @@ -1,11 +1,25 @@ -# Rekalogika Collections Domain +# rekalogika/collections-orm -TBD +A collection class using Doctrine ORM `QueryBuilder` as the data source. Unlike +doing the query in the traditional way, this class allows lazy loading. You can +safely pass the object around, and it will only execute the query when you start +getting items from it. + +The class also implements the `PageableInterface` from the +[`rekalogika/rekapager`](https://rekalogika.dev/rekapager) library. This allows +you to iterate over the collection without loading all the items into memory. +And also useful for creating paginated user interfaces and API outputs. ## Documentation -TBD +[rekalogika.dev/collections](https://rekalogika.dev/collections) ## License -MIT \ No newline at end of file +MIT + +## Contributing + +This library consists of multiple repositories split from a monorepo. Be sure to +submit issues and pull requests to the +[rekalogika/collections](https://github.com/rekalogika/collections) monorepo. \ No newline at end of file