Forem: Zied Hamdi

Rethinking ReBAC: From Accidental Discovery to Zero-Latency Reads

Zied Hamdi — Sun, 12 Apr 2026 01:44:59 +0000

I needed to solve a common hierarchical permission problem on my project... and unknowingly arrived at ideas that extend Google's Zanzibar paper.

Photo by note thanun on Unsplash

I was building a mechanism for "setting-spreading". If a parent company upgraded to a premium tier (enabled a specific feature module), or added a user as a manager of some data, that setting needed to automatically cascade down to specific subsidiaries, team members, and/or related entities based on dynamic rules.

Starting with a single case, the idea was seductive so I extended it to more complex scenarios, before I decided to isolate it as a stand alone solution. Once there, I did my duty of researching whether the problem I was tackling was already solved and open sourced. Surprisingly, it was not so democratized, but it already had a name: ReBAC (Relationship-Based Access Control), formalized by Google's Zanzibar paper.

But as I explored Zanzibar and its modern SaaS implementations (like SpiceDB or Auth0 FGA), I realized a critical bottleneck: Latency.

Here's what I'll cover: the latency problem with standard ReBAC, how AOT materialization solves it, the three abstraction layers that make this engine reusable, and the governance benefits that emerged unexpectedly.

The Zanzibar Latency Paradigm

Google Zanzibar is a phenomenally robust distributed system designed to compute permissions in real-time. It operates as a centralized authorization engine. (Analogy: OIDC scopes and claims, but resolved live across interrelated services)

The standard approach for modern ReBAC environments is to operate as centralized microservices relying on Just-In-Time (JIT) graph traversal. When a user requests access to a resource, the engine calculates the permissions over the network.

This is elegant on paper and adopts a nice microservice SaaS architecture, but in the real world, it becomes a bottleneck:

Network Hops: Every isAuthorized check requires a remote network call.
Read-Time Overhead: As relationship depth increases, computing the graph at read-time causes latency spikes.

If your platform needs sub-millisecond read responses, taking a network hit on every single API check quickly becomes a difficult-to-resolve issue without abandoning the architecture.

The Pivot: Spread at Write, Optimize Read

My approach was iterative—I started denormalizing from the first version. The result is a highly flexible Ahead-Of-Time (AOT) Materialized Engine.

If a user's rights are inherited by their relationships in the hierarchy, we materialize those rights only once: the moment the relationship changes, not each time he wants to access data.

How it Works

Our Materialized ReBAC engine acts as a background hydration pipeline:

The Graph Traverser: When a trigger occurs (e.g., adding an Owner to a Holding Company, or activating a paid module), the engine consults declarative SpreadingConfig rules. It uses a GraphNavigator to traverse the Holding-Subsidiaries database relationships. Through a unified interface, implemented in concrete project-specific code, which is easier to test and debug.
Hydration Jobs: It traverses downstream (or upstream) and injects the resulting permissions or modules directly into the target entities' database records (granting the user inline permissions or activating the paid feature locally).
Constant-Time Reads: Because the permissions are materialized on the target node, authorization at the API level requires zero mathematical computation or graph traversal. It is a simple object check: entity.modules.includes('ANALYTICS') or user.roles.includes('OWNER').

The read latency dropped from network-dependent dozen milliseconds per call (because of network latencies) to absolute zero algorithmic overhead, as it resolves to a db-read that usually is executed along with other data querying in the same network request.

Three Abstraction Axes for Project-Agnostic Design

1. Graph Navigation Abstraction

The engine never hardcodes "how to find neighbors." It consumes an injected GraphNavigator interface that yields adjacent nodes. The engine knows that traversal happens, not how—whether across PostgreSQL, GraphQL, or REST endpoints.

2. Policy Decision Abstraction

The engine delegates all condition evaluations to registered ConditionHandler plugins. Instead of parsing rigid rule strings, it passes typed entities to project-specific code that answers "yes/no" based on business logic (subscription tiers, payment status, etc.).

3. Action Execution Abstraction

The engine uses the Command Pattern for state mutation. It receives an Action payload and blindly calls .execute(). The engine doesn't know if it's granting a role, activating a module, or firing a webhook—it just runs the command.

Testing Advantage: Layered Confidence

Unit tests on the engine itself verify the mechanics: cycle detection, depth limits, queue ordering, FILO rollback logic, and correlation ID tracking. These run in milliseconds with zero infrastructure—pure Go/Rust/TypeScript logic.

Project-specific plugin tests verify the integration: that your CompanyGraphNavigator correctly queries subsidiaries, that your SubscriptionConditionHandler properly evaluates tier levels, and that your RoleMaterializer writes to the correct database tables.

Beyond reusability, the critical advantage of this design is isolation. Because the engine depends only on interfaces, you can test:

Engine behavior with mock plugins (fast, deterministic, exhaustive)
Plugin behavior against real databases using project-specific classes and methods. This removes abstraction layers and eases code reading—no unnecessary mental indirection.

Beyond Speed: Some Nice Side Effects

But beyond speed, some nice side effects showed up: governance.

Because we materialize permissions through an event-driven queue, we can safely emulate (dry-run) outcomes before applying them. This allows for governance patterns that are traditionally difficult to achieve in JIT engines:

Terraform-Style Dry Runs & Pending Changes: By treating permissions as a queue of upcoming events, we can simulate massive cascades and stage "Pending Changes" before they are committed (navigating the tree again to activaite nodes on payment success).
The "Human in the Middle": An administrator can review the simulated propagation tree and explicitly lock specific entities or deactivate spreading on specific modules before executing the materialization. It turns authorization into a clear Permission Staging pipeline that can be submitted for review before getting materialized.
Atomic Correlation & Rollbacks: Every wave of spreading is tied to a correlationId. If an upstream change is undone (or a human makes a mistake), the engine can perfectly roll back the entire materialized state across the tree. Repeatedly in a FILO (first in, last out) manner.
Decision Transparency: Every time the engine refuses to spread a module down a valid path (due to failing a conditional check), it records the detailed structural reasoning in a unified AuditLog for better understanding of the reasons of refusal.
Cycle & Depth Safety: To prevent infinite loops, the queue maintains a strict pathHistory for cycle detection and enforces per-operation-type configuration-specific depth limits to stop cascade exhaustion.

Solving for these edge cases effectively blurred the line between a basic Policy Engine and a full-fledged Identity Governance Administration (IGA) system.

Conclusion

Zanzibar definitively proved that static roles are dead and relationships are the future of access control.

But adopting ReBAC doesn't mean you have to surrender your application to the latency of external API computations. By embracing AOT Materialization, it is possible to build a generic, extensible engine that guarantees the dynamic power of relationship-based access with the uncompromising speed of local read queries.

Svelter Monthly Awards: January 2026 Winners

Zied Hamdi — Tue, 17 Feb 2026 17:38:31 +0000

🏆 Svelter Monthly Awards: January 2026

Today is a big day for Svelter and, I hope, for the Svelte community. After three months of background metric collection and performance analysis, I am finally ready to announce the first-ever batch of Svelter Monthly Winners!

What is a Winner and why did it take three months?

Before we look at the results, you might wonder what exactly a "winner" is on this platform, how it is computed, and why it took three months to determine a single month's results.

On Svelter, a winner isn't just the project with the biggest numbers. To stay true to the mission of detecting momentum without ignoring stability, Svelter uses a three-axis scoring system that requires three months of data to mature:

Speed (Growth Rate): The percentage growth of metrics during the current month. This includes both external signals (GitHub stars, NPM downloads) and community engagement within Svelter (upvotes, favorites, comments).
Acceleration: The change in growth rate compared to the previous month. Svelter rewards projects that are "gaining heat."
Size Factor (The "Stability" axis): We don't just look at percentages. Svelter also factors in raw volume using a logarithmic scale. This ensures that massive, foundational projects aren't put aside just because their growth percentage is naturally lower than a brand-new project.

What makes this scoring unique is how it weighs different signals. While GitHub stars can be ambiguous (is it a bookmark? a thank you? a "maybe later"?) and NPM downloads often come from dependency trees rather than direct choice, community actions like upvotes have one clear purpose: to thank the author. Similarly, favorites signal a deliberate intent to return. These intentional signals receive special weight in the algorithm.

By calculating these three physics of growth, Svelter ensures that winners are projects that are both historically significant and currently trending.

Note: January winners are displayed in February because the month must fully conclude before all downloads and stars can be tallied and verified.

The Svelter Vision: A Meritocracy for Svelte

This rigorous scoring isn't just about math; it's about fulfilling Svelter's broader vision of bringing a true meritocracy to the ecosystem. I built this platform to make it easier for developers to navigate the sea of options. Svelter is designed to:

Discover Adoption: Find what the community is actually using through category-specific trends.
Reward Merit: Give visibility to contributors who grow the community, whether they are writing libraries, blog articles, or even just helpful comments.
Detect Trending Stacks: Use the Echolinks feature to surface emerging tech stacks before they go mainstream.

Whether you are looking for a library by tag or a specific keyword, the goal is to provide a clear path to the most relevant tools.

Central to this meritocracy is permanence. Every monthly winner is graved in Svelter's history, creating a lasting record of community momentum. I am currently developing a feature that will allow winners to display their trophies directly on their own pages and content—turning these achievements into visible badges of recognition.

Evolution: Winners vs. Explore Mode

Translating this vision into a usable product has been a learning experience. When I started building Svelter, I originally only developed the Explore mode. However, I noticed a painful 80% bounce rate. I realized that the effort of finding best performers through the scoring algorithm wasn't immediately visible to new visitors.

To solve this, I added the Winners display mode to expose these results clearly and made it the default view. My goal is to make it immediately obvious who is trending. That said, I've heard that the entry page can still be a bit unclear on first arrival—I would love your suggestions on how to improve the layout or clarity!

The Podium: Overall Winners

After refining how we display these results, let's see which projects actually claimed the top spots for January. You can see the full interactive podium at svelter.me/month/01-2026.

A perfect illustration of our 3-axis logic is the "Supabase Paradox": supabase-js recorded 24.3 million downloads this month. Thanks to its Size Factor, it maintained a strong 5th place despite a 17.8% growth rate. However, it was overtaken by projects like better-svelte-email, which saw a staggering 109% growth rate. Svelter balances raw power with explosive momentum.

🥇 1st Place: better-svelte-email

Category: Boilerplates & Starters
With its massive growth rate and acceleration, it has claimed the first-ever Gold.

🥈 2nd Place: shadcn-svelte

Category: UI Components
A community titan that continues to accelerate. Notably, it saw a 300% surge in community upvotes—a clear signal that developers are actively recognizing its value on Svelter.

🥉 3rd Place: svelte-sonner

Category: Notifications & Modals
The gold standard for toasts, seeing over 283K fresh downloads in January alone.

A Personal Note: I'm also thrilled to share that my own library, user-credits-core, claimed 2nd place in the Miscellaneous category. This three-year-old project had very slow growth initially, leading me to leave it unmaintained. But seeing renewed interest this month—especially knowing these downloads represent genuine adoption rather than dependency tree noise—has inspired me to revisit it. It's a reminder that momentum can reignite even for older projects when the right community finds them.

Congratulations to all the maintainers. Your hard work is what makes our ecosystem thrive. 🚀

If you think the platform could be improved, please write it in the comments, I'd love to hear from you.

Running AirLLM Locally on Apple Silicon: Not So Good

Zied Hamdi — Wed, 28 Jan 2026 11:20:07 +0000

This week, armed with an article on huggingface talking about how AirLLM can run 70b models on 4GB of GPU, I thought. my M4 MacBook Pro (48GB RAM) could run a local coding assistant. Especially that Kilo Code discontinued the free xGrog AI, the timing was as falling from the sky.

The Goal

Create a local xGrog replacement after xGrog became paid on Kilo code. I wanted to run models like:

CodeLlama 13B/70B
DeepSeek-OCR models
Llama 3.1 variants

Funny fact: I didn't have to type all the commands and python files by hand, just asking deepseek to do it for me. And giving directions on failures.

What Actually Worked

✅ Success: AirLLM with Mistral 7B

Using AirLLM's MLX backend, I successfully ran Mistral 7B without quantization. The key was proper PyTorch-to-MLX tensor conversion:

# First, upgrade pip
pip install --upgrade pip

# run python in virtualized env
python -m venv venv  
source venv/bin/activate 

# Install airllm
pip install airllm

# Install PyTorch for Mac (MPS support)
pip install torch torchvision torchaudio

# Optional: for better performance
pip install accelerate

# had to add these (compared to official docs)
pip install mlx-lm 
pip install transformers
pip install safetensors

# airllm_working_mac.py
from airllm import AutoModel
import mlx.core as mx

print("🚀 AirLLM on Apple Silicon - Working Version")
print("="*60)

# Load model
model = AutoModel.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
print("✅ Model loaded successfully")

def generate_response(prompt, max_tokens=100):
    """Generate a response using AirLLM on Mac"""

    # Tokenize
    input_tokens = model.tokenizer(
        [prompt],
        return_tensors="pt",
        return_attention_mask=False,
        truncation=True,
        max_length=512,
        padding=False
    )

    # Convert PyTorch → NumPy → MLX
    pt_tensor = input_tokens['input_ids']
    numpy_array = pt_tensor.cpu().numpy()
    mlx_array = mx.array(numpy_array, dtype=mx.int32)

    print(f"📝 Input length: {mlx_array.shape[1]} tokens")

    # Generate - returns STRING directly
    response = model.generate(
        mlx_array,
        max_new_tokens=max_tokens,
        use_cache=True,
        temperature=0.7
    )

    # Clean up the response (remove extra end tokens)
    cleaned_response = response.replace('</s>', '').strip()
    return cleaned_response

# Test it
test_prompts = [
    "What is the capital of France?",
    "Write a Python function to calculate factorial",
    "Explain quantum computing in simple terms"
]

for i, prompt in enumerate(test_prompts):
    print(f"\n{'='*60}")
    print(f"TEST {i+1}: {prompt}")
    print(f"{'='*60}")

    response = generate_response(prompt, max_tokens=50)
    print(f"🤖 Response:\n{response}")

    # Save to file
    with open(f"response_{i+1}.txt", "w") as f:
        f.write(f"Prompt: {prompt}\n\nResponse: {response}")

print(f"\n{'='*60}")
print("✅ All tests completed! Responses saved to response_*.txt")
print(f"{'='*60}")

Performance: Every question took ~10 minutes, subsequent runs were not faster.

What about bigger models?

❌ Quantization Woes

The biggest limitation: bitsandbytes doesn't work on Mac. This meant:

No 4-bit compression for larger models
48GB RAM limits us to ~13B models max without quantization
mlx-community models (pre-quantized) had loading issues

# This fails on Mac - bitsandbytes needs CUDA
model = AutoModel.from_pretrained("Phind-CodeLlama-34B-v2", compression='4bit')
# Error: "Torch not compiled with CUDA enabled"

❌ File Format Frustrations

Downloaded mlx-community/CodeLlama-13b-Python-4bit-MLX (7GB) but hit:

FileNotFoundError: No safetensors found in [path]

The pre-converted MLX models didn't match MLX-LM's expected file structure.

❌ Performance Reality

Even with successful 7B models:

8.5 minutes for initial AirLLM layer splitting
Significant disk space needed for cache (20+ GB)
Memory pressure even with "small" models

The Architecture Limitation

Apple's MLX framework is promising but immature:

No native quantization support (relies on bitsandbytes)
Model ecosystem is spotty
Documentation gaps for edge cases

Conclusion:

Hosted Solutions Still Win for now. The Mac Studio (M3 Ultra, 192GB RAM) looks like a good silent AI workstation at home. But:

Same quantization issues apply
Still limited by MLX ecosystem maturity
Cost: $7,000+ for hardware vs $20/month cloud

Lessons Learned

AirLLM has significant run overhead, a very "smart" model could compensate for the loading time by executing a complex task, but there are many bottelnecks to only getting it running
Apple Silicon needs native quantization tools
The ecosystem is moving fast but isn't production-ready
For serious work, cloud solutions still dominate

What else I tried on my Mac?

Ollama with smaller models:

brew install ollama
ollama run codellama:13b-python

It just works. No tensor conversions, no quantization headaches, but is very slow: of no help in the real world tasks, and killed memory consumption.
(there are articles out there on how to run it, if you're curious)

So the biggest challenge to learn AI model manipulation today is the hardware entry ticket.
Any alternatives you tried on your side? Tell me in the comments

Bundled Offers with user-credits npm

Zied Hamdi — Tue, 05 Dec 2023 13:34:53 +0000

Unveiling New Features: Bundled Offers and Deduction of Expired Credits

In my continuous effort to enhance user-credits, I'm excited to introduce two groundbreaking features that bring the library to its 1.0.0-beta launch: Bundled Offers and the Deduction of Expired Credits.

Bundled Offers: Simplifying Multi-Offer Management

In the first versions of the user-credits lib, managing multiple offers simultaneously has been a challenge:

How to process multiple orders in a single transaction?
How to monitor service consumption individually?
Which services can be extended with other offers and which cannot?

So the library was able to manage multiple offers, with different tokens and dates, but there was no way to take multiple offers and make out a new single offer from them.

How Bundled Offers Work

Offers can now be combined, enabling the creation of packages similar to those offered by mobile service providers. Picture offering users diverse packages for $20, $50, and $100/month, proposing different quotas of calling hours, mobile data, and additional services like mobile TV or games—all seamlessly combined.

Now, another question arises: if a user buys a $20 package, what happens if they then purchase a $50 one? Or if they want to extend their calling quota only without adding data, are they allowed to do that? Does it extend the expiry date of the calls?

Briefly delving into "Offer Design" in this article, for a more in-depth understanding of how offers work, check this one.

We only need to create a few basic offers, then create the bundles pointing to them by their _id. For the example of the mobile operator, the basic offers would be Call where a token is one minute, Data where a token is one Kb, and TV where there are no tokens, only an expiry date.

From that, we could create the bundled offers, such as the $20 bundled offer proposing 4 hours (quantity= 4 x 60 units) of Calls and 500Mb (quantity= 500 x 1024 units of Kb) of Data.

An IOffer now has a combinedItems field, which is an array of ICombinedOffer.

export interface ICombinedOffer<K extends IMinimalId> {
  _id: K;
  offerGroup: string;
  offerId: K;
  quantity: number;
}

The root offer decides on the expiry date of all the bundled suboffers through its cycle field. But suboffers have the possibility to get their expiry date extended if the offer allows it.

To do that, the field appendDate was introduced; here's its JSDoc which explains it all:

/**
 * Determines how the expiry date is handled at the time of purchase.
 *
 * If {@link IOrder.starts} is not null, no algorithm is executed: it is used as-is, unless the date has passed, in which case, an error occurs.
 *
 * If set to true:
 * - The expiry date extends from the current expiry date of the same offerGroup in {@link IUserCredits.offers[offerGroup]}.
 * - The extension is by the duration specified in {@link IOffer.cycle}.
 *
 * If set to false:
 * - Otherwise, {@link Date.now()} is used as the start date.
 * - The expiry date is calculated by adding {@link IOffer.cycle} to the start date.
 *
 * When the expiry date is reached:
 * - Remaining tokens are deducted from the offerGroup.
 *
 * The computation of remaining tokens:
 * - SUM of tokens from {@link ITokenTimeTable} for the period between start and expires.
 * - This includes added tokens at creation minus all consumptions during that period.
 *
 * As the date expires and nothing can be appended to it:
 * - Unused tokens from that purchase are removed.
 * NOTE1: the field {@link IOrder.quantity} will always multiply {@link IOffer.cycle} to compute the final expiry date.
 * NOTE2: It's not recommended to mix offers with different appendDate values in the same "offerGroup" as it can mislead users.
 */
appendDate: boolean;

Real-Time Credit Tracking

Developers can effortlessly track their users' credit balances and consumption for each bundled offer by calling a single function. Whether checking calling minutes, data usage, or entertainment credits, the new feature provides clear visibility. Additionally, it's through this function that expired orders are deactivated, and their corresponding credits are deducted from the user balance.

Deduction of Expired Credits: Streamlining Credit Management

Efficient credit management involves handling expired credits seamlessly. The Deduction of Expired Credits feature streamlines the process, ensuring users are promptly informed (warning them in advance and logging all operations) and credits are deducted seamlessly. As every token operation is saved in the ITokenTimetable collection, and as different offers can be grouped in the same bag when they have the offerGroup value, consuming tokens is done without knowing which exact order is targeted. But don't worry, we can decide upon that when the time comes.

This is the signature of a token consumption call:

tokensConsumed(


  userId: K, // the user that consumed tokens
  offerGroup: string, // the offerGroup that the user consumed from
  count: number, // the count of tokens consumed
): Promise<ITokenTimetable<K>>;

Each call to this method creates a line, saving the date and the consumed tokens as a negative number in the ITokenTimetable collection. Conversely, each (successful) purchase of any offer triggers a line with a positive number in the same collection. This happens when you call afterExecute: it first contacts the payment gateway to read the state of the payment. If it was paid, multiple operations happen, and among them, a line is added with that date to ITokenTimetable.

IService.afterExecute(order: IOrder<K>): Promise<IUserCredits<K>>;

So when an order expires, we know how many tokens it added to the offerGroup basket, we also know when it started and when it expired. So computing how many tokens of that order were consumed in the allocated time translates to summing up negative entries from ITokenTimetable between the two dates.

An important rule is that orders are kept unchanged from the moment their status becomes "paid". We consider the order entry an archive of what exactly happened: it also copies information from the offer to be able to keep the history clean if ever offers come to change (which is something we don't advise doing, we recommend creating a new offer with the same offerGroup instead). The only thing that can change in an order is its status, and that happens only a few times: before the payment is validated, when the payment fails, or is validated, and when the expiry date hits.

Please note that when the expiry date of an order hits, nothing happens automatically. I decided to let the developer choose when is the opportune time to call the checkForExpiredOrders function. The function does all the work for you. However you have to adopt a strategy on when to call it: it can be a cron that runs every day once for all users, it can be a table that stores the dates of the soon expiring orders and calls those that expired immediately when they end. You name it.

Warnings for Low Credits and Imminent Expiry

const userId = "uniqueUserId";
const warningDuration = 7 * 24 * 3600 * 1000; // 7 days in milliseconds
const lowLimits = [{ min: 60, offerGroup: "calls" }, { min: 5000, offerGroup: "data" }];
const { expired, warnings } = await service.checkForExpiredOrders(userId, warningDuration, lowLimits);

Not only does this function clean the database from the trailing tokens, but it also empowers developers with timely warnings about low credits and imminent expiry of offers. The checkForExpiredOrders function allows users to set warnings for durations and low token levels.

Conclusion

With Bundled Offers and the Deduction of Expired Credits, we're ushering in a new era of simplicity and effectiveness in credit management. These features not only enhance user experience but also open doors to innovative pricing models and subscription plans.

Ready to elevate your credit management game? Host a user-credits library today in a side docker VM and start experimenting without any risks. You might end-up having the credit management as your first micro-service in your app.

This article has been added to the docs of the project

Happy coding!

Ready to use components for credits and payment flow

Zied Hamdi — Wed, 25 Oct 2023 14:26:47 +0000

Unlocking the Power of UserCredits: Making Payments a Breeze for Small Startups

So, you have a brilliant startup idea. You're all set to create the next big thing, but there's a catch: you need to handle payments and credit management. That's where UserCredits comes to the rescue.

Please note that this is still work in progress, but I wrote this article because I'm eager to talk to people who would like to contribute both on user-credits and user-credits-ui

The Birth of UserCredits

It all started when I was building my project, CvLink.in, an AI resume-building platform. I needed a payment system with credit management, but I couldn't find a library tailored to the needs of small startups like mine. So, I took matters into my own hands.

A Solution for the Uncharted Territory

UserCredits is not your run-of-the-mill payment library. It's a versatile, technology-agnostic solution designed to adapt to any front-end framework, making it accessible to developers of all backgrounds. It provides the building blocks for handling payments, offers, and user credits with ease and flexibility.

Unveiling User-Credits-UI: Where the Magic Happens

Now, let's talk about user-credits-ui, the enchanting front-end layer of UserCredits. This part of the library brings a touch of magic to your project, and I promise, it's more fun than reading an academic paper.

Imagine you have an array of offers and you want to display them in a visually appealing way. With user-credits-ui, it's as easy as waving a magic wand. Let's take a look at how we can represent prices using Svelte, but remember, it's adaptable to any front-end technology.

// +layout.svelte
// Set up your resolver and element builder

import { OfferImpl } from '../lib/example/impl/model/OfferImpl';
import Pricing from '../lib/components/Pricing.svelte';

// Mocking values that normally come from the user-credits lib
const freeOffer = new OfferImpl("000", "free", 0, 0);
const startupOffer = new OfferImpl("001", "startup", 0, 1);
const scaleupOffer = new OfferImpl("002", "scaleup", 0, 0);
const enterpriseOffer = new OfferImpl("003", "enterprise", 0, 0);

<Pricing offerList={[freeOffer, startupOffer, scaleupOffer, enterpriseOffer]} />

Pricing is a provided template that creates <Offer> objects. These objects use the resolver to determine how to represent the offers. It uses templates from the very interesting preline project that is built on top of tailwindcss

The magic behind the scenes is the Resolver, an essential part of UserCredits. It transforms raw data into view specifications, ensuring your data is displayed exactly as you want it. Here's a sneak peek into the Resolver:

// Resolver class
export class Resolver implements IResourceResolver {
    getObject<T extends IGeneratorData<T>>(domain: IResourceDomain, data: object): T {
        // Implement your logic here: for example
        switch(domain.type) {
            case "Offer":
                return new OfferProps(data as unknown as IOffer<string>) as T;
        }

    }
}

Now, meet OfferProps. It takes each offer, identifies it, and completes its data. Here's how it works:

// OfferProps class
export class OfferProps implements IOfferProps {
    constructor(data: IOffer<string>) {
        const name = data.name;
// a static switch case could do the trick
        switch (name) {
            case 'free':
                this.name = new ValuePresentation(name);
                // you can add css or tailwind css for example
                this.description = new ValuePresentation('Forever free', 'text-red-500 font-bold', false);
                this.price = new ValuePresentation('Free');
                // and so on for other cases
        }
    }
}

ValuePresentation has a constructor with optional parameters for customizing CSS, providing additional flexibility. The getObject method in the Resolver is an opportunity to enrich the view with elements specific to your platform or add data not available in the IOffer object coming from the UserCredits library.

With UserCredits and user-credits-ui (now for svelte), you can represent offers, payments, and user credits in a straightforward way that adapts to any front-end framework. It's like having your own magical toolkit for creating rich, dynamic views without breaking a sweat.

Whether you're building the next big startup or a passion project, UserCredits has your back. It's time to embrace the magic and make payments a breeze for your small startup.

To learn more about UserCredits and explore the possibilities, check out the UserCredits GitHub repository. And its view layer svelte-user-credits that will be moved to user-credits-ui

Pay-as-you-go, A Flexible Approach to Managing Multiple Offers Simultaneously for a user

Zied Hamdi — Wed, 11 Oct 2023 19:59:59 +0000

A Flexible Approach to Managing Multiple Offers Simultaneously

Hey there, I'm Zied Hamdi, the creator behind UserCredits, and I'm excited to introduce you to the new approach for managing multiple offers and subscriptions simultaneously. As a developer, I understand the importance of flexibility and customization, and I'm here to show you how I've made it a reality.

The Old Way

In the original model, users were restricted to a single subscription plan. This meant that if you wanted to subscribe to different services or enjoy multiple offers, you were out of luck. That one-size-fits-all approach would have been limiting and frustrating for both users and developers.

The New Approach

The innovation introduces the concept of "offer groups" to give users the flexibility they need. Here's how it works:

Offer Groups

Each offer is associated with an "offer group." An offer group is a way to categorize related offers. For example, you might have an offer group for "Mobile TV."

interface IOffer<K extends object> {
  offerGroup: string; // e.g., "Mobile TV"
  // ...
}

Multiple Subscriptions

With this new approach, users can subscribe to multiple offers and services independently.

interface ISubscription<K extends object> {
  offerGroup: string; // e.g., "Mobile TV"
  // ...
}

Personalization

Users can customize their subscription experience to suit their needs. Whether it's mixing and matching different offers or choosing different durations, the power is in the user's hands.

const mobileTvSubscription: ISubscription<ObjectId> = {
  offerGroup: "Mobile TV",
  // ...
};

const phoneAppSubscription: ISubscription<ObjectId> = {
  offerGroup: "Phone App",
  // ...
};

Tracking Expiry Dates and Tokens

Each offer group has its own set of expiry dates and tokens. This ensures that your "Mobile TV" subscription doesn't interfere with your "Phone App" subscription.

const existingOffer: IActivatedOffer | undefined = userCredits.offers.find(
  (offer) => offer.offerGroup === order.offerGroup
);

Enhanced User Experience

This new approach offers an enhanced user experience. It simplifies the management of subscriptions and allows users to enjoy various services with pay-as-you-go balance real time monitoring.

Advantages

The advantages of this new approach are crystal clear:

Flexibility: Users can subscribe to multiple offers and services simultaneously, tailoring their experience to their preferences.
Customization: The ability to mix and match offers and durations ensures a personalized subscription experience.
Simplified Management: Offer groups make it easy to keep track of various subscriptions, tokens, and expiry dates.
Enhanced User Experience: Users have the freedom to enjoy a diverse range of services without constraints.

Get Started

I invite you to explore this new approach and discover the difference it can make for your users. You can check out the full code and implementation details on UserCredits on GitHub.

Feel free to customize and contribute to the project, as I welcome any input and collaboration.

Happy coding!

Zied Hamdi

Javascript: # How to Solve Async IoC Paradox

Zied Hamdi — Fri, 06 Oct 2023 11:50:19 +0000

How to Solve the IoC Infinite Dependency Paradox in JS and TS

In the world of advanced software development, managing dependencies efficiently is crucial. This often involves using Inversion of Control (IoC) containers like Awilix to handle the instantiation and management of objects. While IoC containers are powerful tools for dependency management, one common challenge is ensuring that certain objects, like your IoC container itself, remain singletons, meaning that there is only one instance throughout your application's lifecycle.

The IoC Paradox

Imagine you're building a complex application using an IoC container to manage dependencies, and you need to create an IoC container with various registrations for your services and components. Ideally, you want to create this container only once and use it consistently throughout your application to ensure that the same instances are injected wherever needed. However, there's an issue: you need to initialize the container asynchronously, as many operations like database connection pool is started as asynchronous operations.

The paradox is that you cannot use IOC for that.

The Wider Problem

The IoC paradox is not limited to Awilix; it extends to many IoC libraries. The challenge lies in handling asynchronous calls during registration or resolving of dependencies. Some libraries may not provide straightforward solutions for this, leaving developers to devise their own strategies.

The Initial Solutions

Solution 1: Export the Container

One approach is to export the container instance from the module where it's created and import it wherever needed. However, this will still require you to call the container initializer async method somewhere in your app, and nothing will prevent other developers from calling it again.

Solution 2: Initialize then container and Store in global

Another approach is to initialize the container only once and put it in the global context. While this centralizes container management, it still requires an initial call somewhere in an invasive place in your program to initialize the container. Then storing the value in the global scope is a bad practice for many reasons that I will not detail here. But just think about anyone overriding your instance for example.

Solution 3: Use Dependency Injection

Dependency injection can be employed to pass the container to components and services where it's needed. While this approach maintains the benefits of IOC, it requires an initialization outside the original container file, as it has to be called in async mode (which is not supported by the IOC containers). So we are getting back to the polluting place where we do routines that have to be done before anything relying on the container can load.

An Elegant Solution: The Singleton Pattern

To address these issues, we introduce an elegant solution: the Singleton Pattern for IoC containers. This pattern ensures that the container is created and initialized only once while providing a clean and efficient way to access it without manual storage.


typescript
import { asFunction, asValue, createContainer } from "ioc-library";

export class IoCContainerSingleton {
  private static container: IoCContainer<object>;

  private constructor() {
    // Private constructor to prevent external instantiation
  }

  public static async getInstance(): Promise<IoCContainer<object>> {
    if (IoCContainerSingleton.container) return this.container;

    // Create and initialize the container here...
    // Add your registrations and initialization logic

    return this.container;
  }
}

> Once this is done, it makes no sense to store the singleton in the container as you need an instance of the initialized container to be able to resolve the dependencies in it, and to access that you will anyway need to call this singleton's getInstance() method.

From this point, you will need a singletong implementation for each environment you'd like to run in. eg. test and production. But all the code is isolated in a dedicated file that has only this mission.

Architecting a Pay-As-You-Go Service Library

Zied Hamdi — Tue, 03 Oct 2023 16:06:40 +0000

Architecting Pay-As-You-Go: UserCredits' Adaptable Design

In the previous article, we introduced UserCredits, an open-source project designed to simplify the implementation of pay-as-you-go features in your applications. We explored the core concepts of UserCredits, including offers, orders, user credits, and token timetables. Now, let's dive deeper into the project's architecture, highlighting key design choices that make it both flexible and easy to extend.

The Need for Flexibility

UserCredits aims to provide a flexible and technology-agnostic solution for managing pay-as-you-go features. To achieve this, we separate core business logic from specific database implementations. This separation allows us to support various databases without changing the fundamental logic of the application.

Meet the DAO Factory

At the heart of UserCredits' architecture is the DAO Factory (Data Access Object Factory). It abstracts the data access objects (DAOs) and their dependencies for various entities, such as offers, orders, token timetables, and user credits. By using this factory pattern, we decouple our business logic from the underlying database technology.

Here's a closer look at how it works:

import { IOfferDao, IOrderDao, ITokenTimetableDao, IUserCreditsDao } from "../db/dao";

export interface IDaoFactory<K> {
  getOfferDao(): IOfferDao<K>;
  getOrderDao(): IOrderDao<K>;
  getTokenTimetableDao(): ITokenTimetableDao<K>;
  getUserCreditsDao(): IUserCreditsDao<K>;
}

The IDaoFactory interface defines methods for creating DAO instances for different entities. Each DAO is responsible for interacting with a specific database collection. This separation of concerns makes it easy to switch between database implementations, whether it's MongoDB, PostgreSQL, or another system.

DAOs: Abstracting Database Operations

DAOs (Data Access Objects) serve as the bridge between our business logic and the database. These DAOs provide methods for CRUD (Create, Read, Update, Delete) operations on database entities by default, but can be extended to more specific jobs.

For example, here's a simplified version of the IOfferDao interface:

export interface IOfferDao<K> extends BaseDao<K> {
  createSubOffer(offer: IOffer<K>): Promise<IOffer<K>>;
  findSubOffers(offerId: K): Promise<IOffer<K> | null>;
  // ... other CRUD methods
}

With these DAO interfaces in place, we can implement concrete DAO classes for different database technologies. The key is that the business logic doesn't change; only the underlying DAO implementations do.

Flexible Service Implementation

UserCredits also provides a flexible IService implementation, which serves as a facade for our pay-as-you-go features. This service abstracts complex operations, such as creating orders, executing payments, and checking remaining tokens. By keeping this logic in the service layer, we ensure consistency and simplify the testing process.

export interface IService<K> {
  createOrder(offerId: K, userId: K): Promise<IOrder<K>>;
  execute(order: IOrder<K>): Promise<IUserCredits<K>>;
  orderStatusChanged(orderId: K, status: "pending" | "paid" | "refused"): Promise<IOrder<K>>;
  remainingTokens(userId: K): Promise<IUserCredits<K>>;
}

The IService interface defines methods for performing high-level operations related to pay-as-you-go functionality. This separation of concerns allows us to write tests for our service without worrying about the underlying database implementation.

The Power of Inversion of Control (IoC)

To bring everything together, UserCredits uses Inversion of Control (IoC) through the Awilix library. IoC allows us to manage dependencies and inject the appropriate DAOs into our service and other components.

Here's how it works in practice:

import { asFunction, createContainer } from "awilix";
import { DaoFactory } from "./dao/DaoFactory";

const container = createContainer();

// Register the DAO Factory as a transient value
container.register({
  daoFactory: asFunction(() => {
    const dbFactory = new DaoFactory();
    return dbFactory.init(); // Initialize and configure the database connections
  }),
});

export default container;

With IoC, we can easily swap out different implementations of the DAO Factory based on our database needs. This flexibility is essential for scaling and adapting UserCredits to various projects and technologies.

Conclusion

UserCredits' architecture is designed with flexibility and maintainability in mind. By separating core business logic, abstracting database operations with DAOs, and leveraging Inversion of Control, we've created a powerful framework for managing pay-as-you-go features. This architecture allows us to support different databases, write efficient tests, and adapt to specific project requirements seamlessly.

In the following articles, we'll explore concrete payment processes, explain our tests, and start talking about UX use cases. Stay tuned for more insights into the evolution of this open-source project.

This article provides a more comprehensive overview of UserCredits' architecture, focusing on the DAO Factory, IService implementation, and IoC. It aims to give readers a deeper understanding of how UserCredits achieves flexibility and adaptability in managing pay-as-you-go features.

A pay as you go library for Node.js and Stripe on MongoDb

Zied Hamdi — Fri, 29 Sep 2023 09:12:17 +0000

UserCredits - Simplify Pay-As-You-Go Features for Your Project

As an entrepreneur working on CvLink, I understand the challenges of adding payment and pay-as-you-go features to a project. It's a time-consuming process, and I wanted to build a library in public, documenting the reasons behind my decisions and giving readers the opportunity to provide feedback early in the process.

The library is hosted on GitHub.

While there are existing solutions like LemonSqueezy for implementing pay-as-you-go features, they can be overly complex for simple needs. You may just want to allow users to track their token consumption and pay for them, either before or after usage, without the complexity and cost of a full-fledged service.

What's Typically Needed

To better understand the scope, let's summarize the essential requirements:

Tokens: An abstraction of money to decouple from real currency. For example, users can buy 10 tokens for $10 or 20 tokens for $18.
Real-time tracking of token consumption or balance.
A way for customers to pay for the tokens they've used or to purchase tokens upfront (depending on your billing model).
Currency conversion to display token offers in multiple currencies.
The ability to refund customers for unused tokens.

Concepts

Taking a straightforward approach, here are the core concepts:

Offers: Represent how many tokens users get for their money. This includes scenarios like one-time offers, monthly subscriptions, yearly subscriptions, and discounts based on subscriptions. Offers can also override others with the same overridingKey.
Orders: Represent customers' intentions to purchase an offer. We track their status until the payment is successful.
User Credits: Provide information about a user's token balance and consumption.
Token Timetable: A detailed log of each token consumption, including the date, time, and the service used.

This seems to cover all the essentials for implementing a pay-as-you-go feature in a startup.

Technologies

Projects differ in their database and payment choices, so we expect the need for adapters on these axes. Therefore, it's crucial to keep concepts separate from implementations.

Testing scenarios for buying, consuming, and checking credit balances should be dissociated from the specific technologies used, making them adaptable to different platforms.

Implementation

Here's how I've implemented these concepts:

Offer

An offer specifies its type (e.g., one-time offer or subscription) and a repetition cycle. The parentOffer property specifies relationships, such as discounts for subscribers. Offers with the same overridingKey value override each other.

Multiple sub-offers can share the same overridingKey, representing different discount levels. For example, a free user could buy 10 AI credits for the regular price of $10, a "Starter" user could get a 30% discount, and a "Early adopter" user could have a 50% discount. These offers all have the same overriding key, e.g., overridingKey="10_AI_Credits":

The $10 offer at the root level (parentOffer=null) for default visibility.
The 30% off offer, a child of the "Starter" offer with a weight=1.
The 50% off offer, a child of the "Early adopter" offer with a weight=2.

This way, an "Early adopter", subscribed as a "Starter", gets better privileges by paying 50% less for AI tokens; while keeping the access rules associated to "Starter" accounts.

export interface IOffer {
  cycle: "once" | "weekly" | "monthly" | "yearly";
  kind: "subscription" | "tokens" | "expertise";
  name: string;
  parentOffer: unknown;
  price: number;
  tokenCount: number;
  weight: number;
}

Order

Orders are tied to users intending to purchase an offer. We track their status until payment success. The status field is duplicated to simplify order reading, and the token count is duplicated for robustness.

export interface OrderStatus {
  date: Date;
  message: string;
  status: "pending" | "paid" | "refused";
}

export interface IOrder<K extends object> {
  history: [OrderStatus];
  offerId: K;
  status: "pending" | "paid" | "refused";
  tokenCount: number;
  userId: K;
}

Token Timetable

Token consumption and additions are logged in the token timetable for users to track their token activity.

export interface ITokenTimetable {
  createdAt: Date;
  tokens: number;
  userId: string;
}

User Credits

User credits summarize all transactions, including subscriptions and token balances. Subscriptions duplicate order status for efficient reading.

export interface ISubscription {
  expires: Date;
  offerId: unknown;
  starts: Date;
  status: "pending" | "paid" | "refused";
}

export interface IUserCredits {
  subscriptions: (unknown extends ISubscription ? unknown : never)[];
  tokens: number;
  userId: unknown;
}

Service

The payment interface serves as a facade to manage these concepts. Customers can create orders, execute payments, and check their token balance.

export interface IPayment<T extends object> {
  createOrder(offerId: unknown, userId: unknown): Promise<IOrder<T>>;
  execute(order: IOrder<T>): Promise<IUserCredits>;
  orderStatusChanged(
    orderId: unknown,
    status: "pending" | "paid" | "refused",
  ): Promise<IOrder<T>>;
  remainingTokens(userId: unknown): Promise<IUserCredits>;
}

Implementation

MongoDB was chosen for the initial implementation, but migrating to other databases will be straightforward.
The payment part is yet to be implemented, with Stripe as the first choice, but flexibility for other implementations.
Screens will be developed using SvelteKit, but the library is designed to be adaptable to React, Angular, and Vue as well.

I welcome early contributors to this project, so feel free to contact me if you'd like to contribute or provide feedback.

Thank you for your interest in the UserCredits library! 🚀

500 open-source components for TailwindCSS

Zied Hamdi — Thu, 07 Sep 2023 07:55:31 +0000

I'd like to share my latest discovery with you.
Tailwind Elements is currently, the most popular 3rd party UI kit for TailwindCSS with over 10k Github stars. It's a huge collection of stunning components made with attention to the smallest detail. Forms, cards, buttons, and hundreds of others. All components have dark mode and very intuitive theming options. The project is supported by an engaged community on GitHub, I recommend you check it out and join one of the many discussions.

You will find installation instructions here, and you can track the progress of the project live here.

The project was kickstarted by @MDBootstrap, a group of open-source developers behind MDB UI Kit - a high-quality UI kit for Bootstrap, and also behind MDB GO - hosting and deployment platform.

I highly recommend you to check it out!

Article No Longer Available

With SvelteKit

If you have a SvelteKit app and want to try out Tailwind Elements, here's a great tutorial on how to set up your app.

How I integrated preline to work in SvelteKit

Zied Hamdi — Fri, 05 May 2023 10:36:56 +0000

As I'm leaving medium to come here, this is my first article on dev.to. I hope you'll like it.

I decided to launch a resume builder with Sveltkit at CvLink.

After testing Flowbite, I had a clear preference for the look and feel and component offer of Preline.

But it was not easy to have the components react to click events. So I'm sharing what I did because I couldn't find any info on the web.

Steps

I'm presenting the steps briefly as I suppose that's what you're waiting for: getting it done and walk away :-)

install Preline

pnpm add preline

Add TailwindCss

to do the equivalent of npx in pnpm:
npx svelte-add@latest tailwindcss pnpm i

Install svelte-add globally, then use it to add tailwindcss
pnpm install -g svelte-add svelte-add tailwindcss

Configure tailwind

tailwind.config.js

const config = {
content: [
"./src/**/*.{html,js,svelte,ts}",
"./node_modules/preline/dist/*.js",
],

    theme: {
        extend: {},
    },

    plugins: [
        require('preline/plugin')
    ],
    darkMode: 'class',
};

module.exports = config;

Adapt Preline js files

Instead of having the js load at document.on('load') ex:

document.addEventListener('load', window.HSAccordion.init());

We make it load lazily when a component displays for its first time.

Files were copied from preline

I copied ./core/component.js to a local folder ./preline/component

And copied HSAccordion to ./accordion/Accordion.js next to its Svelte component

Skipping js-loading when in SSR

Accordion

When index.js was loaded, it attached components' js to window like follows:

window.HSAccordion = new HSAccordion();
document.addEventListener('load', window.HSAccordion.init());

I moved that init code to the AccordionItem component, checking i'm in the browser before initializing like follows:

<script>
    import Accordion from './Accordion';

    if(typeof window !== 'undefined') {
        console.log(  "initializing accordion" )
        window.HSAccordion = new Accordion();
        window.HSAccordion.init();
    }
    export let name;
</script>

The code for the accordion is pretty direct, then:
AccordionItem.svelte

<script>
    import Accordion from './Accordion';

    if(typeof window !== 'undefined') {
        console.log(  "initializing accordion" )
        window.HSAccordion = new Accordion();
        window.HSAccordion.init();
    }
    export let name;
</script>

<li class='hs-accordion' id='account-accordion'>
    <a
        class='hs-accordion-toggle flex items-center gap-x-3.5 py-2 px-2.5 hs-accordion-active:text-blue-600 hs-accordion-active:hover:bg-transparent text-sm text-slate-700 rounded-md hover:bg-gray-100 dark:bg-gray-800 dark:hover:bg-gray-900 dark:text-slate-400 dark:hover:text-slate-300 dark:hs-accordion-active:text-white'
        href='javascript:;'>
        <slot name='icon' />
        <slot name='name'>{name}</slot>

        <svg
            class='hs-accordion-active:block ml-auto hidden w-3 h-3 text-gray-600 group-hover:text-gray-500 dark:text-gray-400'
            width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'>
            <path d='M2 11L8.16086 5.31305C8.35239 5.13625 8.64761 5.13625 8.83914 5.31305L15 11'
                        stroke='currentColor' stroke-width='2' stroke-linecap='round'></path>
        </svg>

        <svg
            class='hs-accordion-active:hidden ml-auto block w-3 h-3 text-gray-600 group-hover:text-gray-500 dark:text-gray-400'
            width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'>
            <path d='M2 5L8.16086 10.6869C8.35239 10.8637 8.64761 10.8637 8.83914 10.6869L15 5' stroke='currentColor'
                        stroke-width='2' stroke-linecap='round'></path>
        </svg>
    </a>

    <div id='account-accordion-child'
             class='hs-accordion-content w-full overflow-hidden transition-[height] duration-300 hidden'>
        <slot name='content' />
    </div>
</li>

I created a repository where you can benefit of the work directly.

Known bugs: Sometimes the js is not loaded, happens in dev mode, I still didn't check if it happens in prod.