DEV Community: Ahmed Niazy

Advanced TypeScript Type System — The Complete Deep Dive

Ahmed Niazy — Tue, 17 Feb 2026 06:47:52 +0000

📚 Table of Contents

Quick Type System Refresher
How Type Narrowing Works Internally
Conditional Types — Beyond Basics
Distributive Conditional Types Deep Mechanics
The infer Keyword — Pattern Matching in Types
Mapped Types Internals
Key Remapping & Property Filtering
Template Literal Types as a Type-Level DSL
Recursive Types & Type-Level Recursion
Building Advanced Custom Utility Types
Reverse Engineering DefinitelyTyped
Variance — The Hidden Foundation
Union to Intersection — The “Variance Hack” Explained
Higher-Order Types & Type-Level Function Composition
Advanced infer Tricks (Tuples, Promises, and More)
Type-Level Parsing (String Manipulation)
Building a Fully Type-Safe Event System
Exhaustiveness Checking with never
Compiler Limits — What Actually Breaks
Performance Impact of Complex Types
Practical Guidelines for Production Systems

1️⃣ Quick Type System Refresher (In 5 Minutes)

TypeScript is:

Structurally typed
Gradually typed
Erased at runtime
Control-flow aware
Turing complete at the type level (with limits)

Structural Typing

type User = { id: string; name: string };

type Admin = { id: string; name: string; role: string };

const admin: Admin = {
  id: "1",
  name: "Ahmed",
  role: "super",
};

const user: User = admin; // ✅ Valid (structural typing)

Type compatibility depends on structure, not name.

2️⃣ How Type Narrowing Works Internally

Type narrowing is powered by Control Flow Analysis (CFA).

When TypeScript analyzes this:

ts function process(value: string | number) { if (typeof value === "string") { value.toUpperCase(); } }

Internally:

A Control Flow Graph (CFG) is created.
Each branch refines possible types.
The compiler intersects original type with the narrowed constraint.

Example: Discriminated Union

`ts
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; side: number };

function area(shape: Shape) {
if (shape.kind === "circle") {
return Math.PI * shape.radius ** 2;
}
}
`

TypeScript understands:

kind is a literal discriminator
Each variant is mutually exclusive
The if branch removes incompatible members

This is not magic — it’s a refinement process.

3️⃣ Conditional Types — The Core Engine

Conditional types are the backbone of advanced type logic.

`ts
type IsString = T extends string ? true : false;

type A = IsString<"hello">; // true
type B = IsString; // false
`

What Actually Happens?

The compiler:

Substitutes T
Checks assignability (T extends U)
Produces one branch

This is type-level branching.

4️⃣ Distributive Conditional Types — Hidden Power

When a naked type parameter appears on the left side of extends, distribution occurs.

`ts
type Wrap = T extends any ? { value: T } : never;

type Result = Wrap;
`

Expands into:

ts { value: string } | { value: number }

Why?

Because unions are treated element-wise when T is “naked”.

Prevent Distribution

ts type Wrap<T> = [T] extends [any] ? { value: T } : never;

Wrapping in a tuple disables distribution.

5️⃣ The `infer` Keyword — Type Pattern Matching

infer allows extracting types during conditional matching.

Extract Return Type

ts type GetReturn<T> = T extends (...args: any[]) => infer R ? R : never;

Extract First Argument

ts type FirstArg<T> = T extends (arg: infer A, ...rest: any[]) => any ? A : never;

Deep Extraction Example

ts type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

This is essentially pattern matching on types.

6️⃣ Mapped Types — Iteration at Type Level

Mapped types iterate over keys.

ts type Readonly<T> = { readonly [K in keyof T]: T[K]; };

Mechanism:

keyof T becomes a union of keys
[K in ...] iterates key-by-key
A new type is constructed

7️⃣ Key Remapping & Property Filtering

Since TypeScript 4.1:

`ts
type Prefix = {

};
`

Filtering Keys

`ts
type RemoveId = {

};
`

Returning never removes the key entirely.

8️⃣ Template Literal Types — Compile-Time String Engine

ts type EventName<T extends string> =on${Capitalize}`;

type E = EventName<"click">; // "onClick"
`

Cartesian Explosion

`ts
type Lang = "en" | "ar";
type Key = "title" | "desc";

type TranslationKey = ${Lang}_${Key};
`

Expands into 4 combinations.

⚠️ This can grow exponentially with big unions.

9️⃣ Recursive Types — Type-Level Recursion

Example: DeepReadonly

ts type DeepReadonly<T> = T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;

What’s happening?

Checks if T is object
Recursively transforms properties
Stops at primitives

⚠️ Recursion depth is limited (often ~50 instantiations, depends on context).

🔟 Building Advanced Custom Utility Types

DeepPartial

ts type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;

Keys By Value Type

ts type KeysByValue<T, V> = { [K in keyof T]: T[K] extends V ? K : never; }[keyof T];

Indexing collapses the mapped results into a union.

Flatten Nested Object (Caution: can be expensive)

ts type Flatten<T> = { T[K] extends object ? Flatten<T[K]> : T[K]; };

1️⃣1️⃣ Reverse Engineering DefinitelyTyped

Example inspired by React:

ts type ComponentProps<T> = T extends React.JSXElementConstructor<infer P> ? P : T extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[T] : {};

What’s happening?

If it’s a component → extract props via infer
If intrinsic element → lookup built-in props
Otherwise → {}

DefinitelyTyped heavily uses:

Deep conditional nesting
infer extraction
Mapped transformations
Distributive tricks
Intersections to merge constraints

1️⃣2️⃣ Variance — The Hidden Foundation

Variance defines how subtyping behaves with generics.

There are 4 flavors:

Covariant: preserves subtype direction
Contravariant: reverses subtype direction
Bivariant: both directions (often unsafe)
Invariant: neither direction

Covariance Example

`ts
type Box = { value: T };

type A = Box;
type B = Box;

const a: A = { value: "x" };
const b: B = a; // ✅
`

Contravariance (Function Parameters)

`ts
type Fn = (value: T) => void;

let fn1: Fn;
let fn2: Fn;

fn2 = fn1; // ✅
fn1 = fn2; // ❌ unsafe
`

Why? Because if fn1 expects string | number, assigning a function that only accepts string can break.

Bivariance (Historical Loophole)

Methods on object types can behave bivariantly for compatibility:

ts type Handler<T> = { handle(value: T): void; };

This can be convenient, but also a source of unsoundness.

1️⃣3️⃣ Union to Intersection — The “Variance Hack” Explained

This classic utility works because of function parameter contravariance.

ts type UnionToIntersection<U> = (U extends any ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;

What’s happening step-by-step?

Given:

ts type U = { a: string } | { b: number };

Step 1: Distribute into functions

ts U extends any ? (arg: U) => void : never

Becomes:

ts (arg: { a: string }) => void | (arg: { b: number }) => void

Step 2: Infer the parameter

Because parameters are contravariant, inference collapses into an intersection:

ts (arg: infer I) => void

Result:

ts { a: string } & { b: number }

This is a deliberate “exploit” of variance mechanics.

1️⃣4️⃣ Higher-Order Types & Type-Level Function Composition

TypeScript doesn’t support true Higher-Kinded Types (HKTs), but we can simulate them.

`Apply` — Calling a Type-Level Function

ts type Apply<F, T> = F extends { type: (arg: T) => infer R } ? R : never;

Defining a “type-level function”

`ts
type ToArray = {
type: (arg: T) => T[];
};

type R = Apply; // string[]
`

Type-Level Composition (“Piping”)

ts type Pipe<A, B> = B extends (arg: infer T) => any ? A extends (arg: any) => T ? (arg: Parameters<A>[0]) => ReturnType<B> : never : never;

This is compile-time plumbing: connecting one function type to another.

1️⃣5️⃣ Advanced `infer` Tricks (Tuples, Promises, and More)

Head / Tail of a Tuple

`ts
type Head =
T extends [infer H, ...any[]] ? H : never;

type Tail =
T extends [any, ...infer R] ? R : never;
`

Reverse a Tuple (Recursive)

ts type Reverse<T extends any[]> = T extends [infer H, ...infer R] ? [...Reverse<R>, H] : [];

Extract Promise Inner Type

ts type AwaitedLike<T> = T extends Promise<infer U> ? U : T;

1️⃣6️⃣ Type-Level Parsing (String Manipulation)

Template literal types let us parse strings.

Extract Route Params

ts type ExtractParams<T extends string> = T extends${string}:${infer Param}/${infer Rest}? Param | ExtractParams<Rest> : T extends${string}:${infer Param}`
? Param
: never;

type Params = ExtractParams<"/user/:id/post/:postId">;
// "id" | "postId"
`

This is a real type-level parser.

1️⃣7️⃣ Building a Fully Type-Safe Event System

Define events:

ts type EventMap = { click: { x: number; y: number }; login: { userId: string }; logout: void; };

Listener:

ts type Listener<E extends keyof EventMap> = (payload: EventMap[E]) => void;

Emitter:

`ts
class Emitter {
on(event: E, listener: Listener) {}

emit(event: E, payload: EventMap[E]) {}
}
`

Usage:

`ts
const emitter = new Emitter();

emitter.emit("click", { x: 10, y: 20 }); // ✅
emitter.emit("click", { userId: "1" }); // ❌
`

keyof constraints
indexed access EventMap[E]
literal inference

1️⃣8️⃣ Exhaustiveness Checking with `never`

ts function assertNever(x: never): never { throw new Error("Unexpected value"); }

`ts
type Shape =
| { kind: "circle" }
| { kind: "square" };

function handle(shape: Shape) {
switch (shape.kind) {
case "circle":
return;
case "square":
return;
default:
assertNever(shape); // ✅ compiler error if a case is missing
}
}
`

1️⃣9️⃣ Compiler Limits — What Actually Breaks

TypeScript has:

Instantiation depth limits
Union size limits
Memory thresholds

Extremely Dangerous Pattern (Union Explosion)

ts type Explode<T> = T extends any ? { a: T } | { b: T } : never;

Large unions here can grow exponentially.

2️⃣0️⃣ Performance Impact of Complex Types

TypeScript types are evaluated during compilation.

Heavy constructs increase:

Type instantiation count
Union expansion
Recursive resolution depth
IDE memory usage

Common Errors

txt Type instantiation is excessively deep and possibly infinite.

txt Expression produces a union type that is too complex to represent.

What Causes Slowness?

Deep recursive mapped types
Large distributive conditional chains
Template literal cartesian explosions
Intersections over wide unions

2️⃣1️⃣ Practical Guidelines for Production Systems

✅ Prefer Shallow Utilities

Avoid deep recursion unless necessary.

✅ Avoid Naked Distribution When Not Needed

Wrap generics in tuples:

ts [T] extends [any] ? ... : ...

✅ Break Complex Types Into Steps

Instead of:

ts type MegaType<T> = Deep<Transform<Extract<T>>>;

Do:

ts type Step1<T> = Extract<T>; type Step2<T> = Transform<T>; type Step3<T> = Deep<T>; type MegaType<T> = Step3<Step2<Step1<T>>>;

✅ Profile Large Codebases

Use:

bash tsc --extendedDiagnostics

🧠 Final Thoughts

TypeScript’s type system is no longer just static annotations.

It is:

A functional programming system
A compile-time evaluator
A pattern-matching engine
A string manipulation engine
A transformation DSL

But with great power comes:

Complexity
Compilation cost
Maintenance challenges

Mastering it allows you to build libraries at the level of:

React
Redux Toolkit
Zod
tRPC
Prisma

A Deep Dive Into Schema.org Structured Data For SEO

Ahmed Niazy — Thu, 05 Feb 2026 15:22:02 +0000

This article explains a reusable structured data module.
It is typically implemented as a composable or utility.
It is usually written in TypeScript.
It exports a factory function.
That factory returns multiple helper functions.
Each helper function builds a Schema.org JSON LD object.
These objects are meant to be embedded in the page HTML.
Typically you embed them inside a script tag.
The script tag type should be application/ld+json.
Search engines read that JSON LD.
They use it to understand your pages.
They may produce rich results.
They may improve entity understanding.
They may improve crawl interpretation.

Important note

This composable only generates plain JavaScript objects.
It does not inject them into head by itself.
You still need to connect the output to your head management.
In most frameworks, you can do that via your head management system.
Or you can use a dedicated structured data integration.
The composable focuses on generation logic.

What this file contains

The file contains TypeScript interfaces.
Each interface defines the input shape for a generator.
Then the file defines the schema module.
Inside the schema module there are shared dependencies.
There is a route reference.
There is a locale reference.
There is a configuration reference.
Then there is baseUrl.
baseUrl comes from your configuration.
If baseUrl is missing, it falls back to a default domain.

After that, the file defines many generator functions.
All of them return a schema object.
Most return an object unconditionally.
One generator returns null when there is no data.
That generator is the FAQ schema generator.

How to use outputs in SEO

Search engines do not rank pages just because JSON LD exists.
But JSON LD helps them understand.
Better understanding can lead to better presentation.
Better presentation can lead to better click through.
Rich results can add extra screen space.
Extra screen space can increase trust.
It can also reduce ambiguity.

Structured data can help with

Entity disambiguation
Site identity
Publisher identity
Breadcrumb display
FAQ rich results
Job posting rich results
Product like availability signals for services
App rich results for SoftwareApplication

The exact rich result eligibility depends on search engine rules.
But the shapes used here are aligned with common Schema.org patterns.

Shared dependencies inside the schema module

The module reads the current route.
It reads the current locale.
It reads baseUrl.
These three values are used by helper methods.
The schema generators themselves accept explicit URLs.
So they are reusable across pages.

The helper methods focus on

Getting the current page URL in a consistent way
Building breadcrumb items from the route path

Now we will go function by function.

Organization schema

Generator

Organization schema generator

Goal

This function generates a Schema.org Organization entity.
An Organization is often used as the publisher.
It can also represent your brand entity.
It can connect your website to social profiles.
It can add contact and address info.
It can help build a knowledge graph entity.

Input interface

OrganizationSchemaOptions has these fields

Required

name
url
logo

Optional

alternateName
description
founder
foundingDate
foundingLocation
telephone
email
address
contactPoint
sameAs

Output shape

The base object includes

[at]context set to https://schema.org
[at]type set to Organization
name
url
logo

Then it conditionally adds optional fields.
It only adds a field if you provided it.
This prevents empty fields.
That is helpful for clean output.

Address field

If address exists, it builds a PostalAddress object.
It sets [at]type to PostalAddress.
Then it spreads the address fields.
Those fields are

streetAddress
addressLocality
addressRegion
postalCode
addressCountry

ContactPoint field

If contactPoint exists and is not empty, it maps each entry.
Each entry becomes a ContactPoint object.
It sets [at]type to ContactPoint.
Then it spreads the input.
This can represent sales, support, or other contact types.

sameAs field

If sameAs exists and is not empty, it adds sameAs.
sameAs is a list of URLs.
Common examples are

Facebook page URL
Instagram profile URL
LinkedIn company page URL
X profile URL
YouTube channel URL

SEO value of Organization schema

It defines who owns the site.
It defines your brand name and logo.
It can connect your brand to social profiles.
It helps search engines connect content to a publisher.
It can reduce ambiguity when your brand name is generic.
It can help create a consistent entity graph.

WebPage schema

Generator

WebPage schema generator

Goal

This function describes a single web page.
It supports core page metadata.
It can connect the page to a website.
It can connect the page to a publisher.
It can attach a mainEntity.

Input interface

WebPageSchemaOptions

Required

url
name
description
inLanguage

Optional

isPartOf
publisher
mainEntity
datePublished
dateModified

Output shape

The base object includes

[at]context https://schema.org
[at]type WebPage
url
name
description
inLanguage

isPartOf field

If isPartOf exists, it builds a Website object.
It sets [at]type to Website.
Then it adds url and name.
This connects a page to a website entity.

publisher field

If publisher exists, it builds an Organization object.
It sets [at]type to Organization.
It sets name.
It sets logo as an ImageObject.
The logo ImageObject has

[at]type ImageObject
url

mainEntity field

If mainEntity exists, it attaches it as is.
The type is Record.
This means you can pass any schema object.
For example, you can pass a RealEstateAgent.
Or you can pass an Article.
Or you can pass a FAQPage.
This is flexible.
But it also means you need to validate your own mainEntity.

datePublished and dateModified

If provided, they are added directly.
They should be ISO 8601 date strings.
Examples

2026-02-03
2026-02-03T10:00:00Z

SEO value of WebPage schema

It clarifies the canonical page identity.
It clarifies language.
It can connect to a website and publisher.
It can connect to a main entity.
It can help search engines interpret page intent.

BreadcrumbList schema

Generator

BreadcrumbList schema generator

Goal

BreadcrumbList helps search engines understand hierarchy.
It may show breadcrumb rich results.
It can also help with sitelinks context.

Input interface

BreadcrumbSchemaOptions

items is an array of name and item URL.

Output shape

The output includes

[at]context https://schema.org
[at]type BreadcrumbList
itemListElement as an array of ListItem

Each ListItem includes

[at]type ListItem
position starting at 1
name
item

SEO value of BreadcrumbList

It clarifies the user journey.
It clarifies category and page relationships.
It can appear in SERP snippets.
It can reduce URL clutter in results.

RealEstateAgent schema

Generator

RealEstateAgent schema generator

Goal

This function describes a RealEstateAgent entity.
This is relevant for a real estate platform.
It can be used for company pages or agent profiles.

Input interface

RealEstateAgentSchemaOptions

Required

name
url

Optional

image
telephone
email
priceRange
address
geo
openingHoursSpecification
sameAs
areaServed

Output shape

Base object

[at]context https://schema.org
[at]type RealEstateAgent
name
[at]id equals options.url
url equals options.url

This is a common pattern.
Using [at]id can help connect entities.

image field

If image exists, it is added directly.
You should provide an absolute URL.

telephone and email

If present, they are added as strings.

priceRange

If present, it is added.
It is usually a string like

$$
$1000 to $5000

address

If present, it becomes a PostalAddress.
Same structure as the Organization address.

geo

If present, it becomes GeoCoordinates.
It sets

[at]type GeoCoordinates
latitude
longitude

openingHoursSpecification

If present and non empty, each item becomes OpeningHoursSpecification.
It sets [at]type OpeningHoursSpecification.
Then it spreads the input fields.
Those include

dayOfWeek as an array of strings
opens
closes

sameAs

If present, it is added as a list of URLs.

areaServed

If present, it becomes a City.
It sets [at]type City.
It sets name.

SEO value of RealEstateAgent schema

It defines an entity that can be referenced.
It can support local intent signals.
It can connect contact details and location.
It can help clarify the business type.

LocalBusiness schema

Generator

LocalBusiness schema generator

Goal

This function describes a LocalBusiness entity.
This is a generic business listing schema.
It can represent branches or offices.

Input interface

LocalBusinessSchemaOptions

Required

name
url

Optional

image
telephone
priceRange
address
geo
openingHoursSpecification
sameAs

Output shape

Base object

[at]context https://schema.org
[at]type LocalBusiness
name
[at]id equals url
url

Optional fields are handled similarly to RealEstateAgent.

SEO value of LocalBusiness schema

It supports local SEO context.
It provides address and geo coordinates.
It can support knowledge panel consistency.
It can connect opening hours.

Service schema

Generator

Service schema generator

Goal

This function describes a Service.
A Service schema can represent what you offer.
It can connect a service type to a provider.
It can attach offers.

Input interface

ServiceSchemaOptions

Required

serviceType
provider

Optional

areaServed
description
offers

Provider object

provider has

name
url
logo
sameAs optional

Output shape

Base object

[at]context https://schema.org
[at]type Service
serviceType
provider as an Organization

Provider is set to

[at]type Organization
name
url
logo

Provider sameAs

If provider.sameAs exists and is non empty, it is attached.
This uses a type cast to edit schema.provider.

areaServed

If present, it becomes a Place.
It sets

[at]type Place
name

description

If present, it is added.

offers

If offers exists, it creates an Offer object.
It sets [at]type Offer.
Then it spreads all fields from offers.

Offer fields can include

url
priceCurrency
price
priceSpecification
availability

priceSpecification

If priceSpecification exists, it becomes a PriceSpecification object.
It sets [at]type PriceSpecification.
Then it spreads the priceSpecification fields.
Those fields can include

price
priceCurrency
validFrom

SEO value of Service schema

It clarifies what you do.
It can connect a service to the provider entity.
It can expose offer like details.
It can support better matching to intent.

BlogPosting schema

Generator

BlogPosting schema generator

Goal

This function builds BlogPosting structured data.
It is used for blog content.
It can help eligibility for article rich results.
It can help publishers clarify authorship.

Input interface

BlogPostingSchemaOptions

Required

mainEntityOfPage.url
headline
author.name
publisher.name
publisher.logo
datePublished

Optional

description
image
author.url
dateModified

Output shape

Base object includes

[at]context https://schema.org
[at]type BlogPosting
mainEntityOfPage as WebPage with [at]id set to URL
headline
author as Person with name
publisher as Organization with name and logo ImageObject
datePublished

Conditional fields

If description exists, it is added.
If image exists, it is added.
If author.url exists, author.url is attached.
If dateModified exists, dateModified is attached.

SEO value of BlogPosting schema

It clarifies that content is a blog post.
It clarifies author and publisher.
It provides publish and modified dates.
It helps search engines understand content freshness.

Article schema

Generator

Article schema generator

Goal

This function builds Article structured data.
It is similar to BlogPosting.
It is useful for editorial content and guides.

Input interface

ArticleSchemaOptions

Required

mainEntityOfPage.url
headline
author.name
publisher.name
publisher.logo
datePublished

Optional

description
image string or string array
author.url
dateModified
keywords

Output shape

Base object includes

[at]context https://schema.org
[at]type Article
mainEntityOfPage WebPage with [at]id
headline
author Person
publisher Organization and ImageObject logo
datePublished

Image handling

If image exists, it ensures schema.image is an array.
If the input is already an array, it uses it.
If the input is a string, it wraps it as a single element array.
This is convenient for consumers.

keywords

If keywords exists, it is added.
This is a plain string in this implementation.
Sometimes keywords is provided as comma separated.

SEO value of Article schema

It clarifies content type as an article.
It improves author and publisher clarity.
It can help with article rich results.
It supports date signals.

SoftwareApplication schema

Generator

SoftwareApplication schema generator

Goal

This function describes a software application.
This is appropriate for a SaaS platform.
It can help search engines understand your product.
It can connect offers and ratings.

Input interface

SoftwareApplicationSchemaOptions

Required

name
applicationCategory
description
url
author.name
author.url

Optional

operatingSystem
image
offers
aggregateRating
applicationSubCategory
softwareVersion

Output shape

Base object includes

[at]context https://schema.org
[at]type SoftwareApplication
name
applicationCategory
description
url
author as Organization with name and url

operatingSystem

If present, it is attached.
For web apps, you might use Web.
For native apps, you might use iOS or Android.

image

If present, it is attached.
Provide an absolute URL.

offers

If offers exists, it builds an Offer object.
Offer includes

[at]type Offer
price
priceCurrency
availability
url optional

aggregateRating

If present, it becomes AggregateRating.
It sets

[at]type AggregateRating
ratingValue
ratingCount

applicationSubCategory and softwareVersion

If present, they are attached.
These can help describe versions and sub type.

SEO value of SoftwareApplication schema

It clarifies your product as software.
It can display pricing and availability.
It can support rating snippets depending on policy.
It helps search engines understand app category.

JobPosting schema

Generator

JobPosting schema generator

Goal

This function describes a job listing.
JobPosting can enable job rich results.
It can help distribute your job posts.

Input interface

JobPostingSchemaOptions

Required

title
description
datePosted
validThrough
employmentType
hiringOrganization.name

Optional

identifier
hiringOrganization.sameAs
hiringOrganization.logo
jobLocation
remote
applicantLocationRequirements
baseSalary
responsibilities
qualifications
skills
educationRequirements
experienceRequirements
incentiveCompensation
industry
jobBenefits

Output shape

Base object includes

[at]context https://schema.org/
[at]type JobPosting
title
description
datePosted
validThrough
employmentType
hiringOrganization as Organization

identifier

If identifier exists, it becomes PropertyValue.
It sets

[at]type PropertyValue
name
value

hiringOrganization fields

If sameAs exists, it is attached.
If logo exists, it is attached.

jobLocation

If jobLocation exists, it becomes Place with PostalAddress.

remote

If remote is provided, it sets schema.remote to a string.
It uses options.remote.toString.
This results in true or false as strings.
Some consumers expect a boolean.
But this is the current behavior.
If you depend on strict schema validation, review this.

applicantLocationRequirements

If provided, it becomes a Country object with name.

baseSalary

If provided, it builds MonetaryAmount.
It sets

[at]type MonetaryAmount
currency
value as QuantitativeValue

QuantitativeValue includes

[at]type QuantitativeValue
unitText
minValue optional
maxValue optional

Responsibilities and other text fields

If provided, they are attached as strings.
This includes responsibilities, qualifications, skills, and more.

SEO value of JobPosting schema

It can enable job rich results.
It improves job distribution.
It clarifies salary and location.
It clarifies employer identity.

FAQPage schema

Generator

FAQPage schema generator

Goal

This function creates FAQPage structured data.
FAQ structured data can produce FAQ rich results.
It is often used on landing pages.
It can also be used on documentation pages.

Input interface

FAQSchemaOptions

items is an array of question and answer.

Behavior for empty data

If items is missing or empty, the function returns null.
This is important.
It prevents injecting an empty FAQPage.
It also avoids invalid schema.

Output shape

[at]context https://schema.org
[at]type FAQPage
mainEntity as an array

Each item becomes

[at]type Question
name set to the question
acceptedAnswer as Answer
acceptedAnswer.text set to the answer

SEO value of FAQPage schema

It answers common questions directly.
It can expand SERP snippets.
It can increase click through when implemented correctly.
It can improve relevance understanding.

Helper Current page URL builder

Goal

This helper builds the current page absolute URL.
It uses the route path.
It ensures language prefix is consistent.
It removes locale segments from the route.

Logic

path is route.path
langPrefix is /en when locale is en
otherwise langPrefix is empty
cleanPath removes a leading /en or /ar
if the route becomes empty, it uses /
it returns baseUrl + langPrefix + cleanPath

Why this matters for SEO

Absolute URLs are preferred inside schema.
A consistent URL reduces duplicate entity identities.
Locale paths can cause duplicates if not handled.
This helper ensures a stable, localized URL.

Helper Breadcrumb builder from route

Goal

This helper generates breadcrumb items automatically.
It uses route.path.
It splits the path into segments.
It skips locale segments.
It builds cumulative URLs.
It generates readable names.

Output

It returns an array of

name
item

The first breadcrumb is always Home.
If locale is ar, it uses العربية.
If locale is not ar, it uses Home.
The Home item is baseUrl + /.

Name generation details

For each non locale segment

it splits by hyphen
it capitalizes the first letter of each word
it joins with space

So a segment like property-management becomes
Property Management

URL generation details

It builds currentPath incrementally.
It uses langPrefix based on locale.
It builds fullPath as baseUrl + langPrefix + currentPath.

Then it pushes { name, item }.

SEO value of auto breadcrumbs

Even if you render breadcrumbs in UI, schema breadcrumbs help crawlers.
They provide a machine readable hierarchy.
They can reduce ambiguity on nested routes.
They can improve display snippets.

Integration guidance

The composable returns generator functions.
A typical usage pattern is

Build schema objects based on page data
Serialize them to JSON
Inject into head as JSON LD

Example high level approach

For a homepage
- Organization
- WebPage
- BreadcrumbList with just Home
- Service or LocalBusiness as mainEntity
For a blog post page
- BlogPosting
- WebPage with mainEntity set to BlogPosting
- BreadcrumbList
For a guide page
- Article
- WebPage with mainEntity set to Article
For a FAQ landing page
- FAQPage
- WebPage with mainEntity set to FAQPage
For careers
- JobPosting
- WebPage with mainEntity set to JobPosting

Data quality checklist

Use absolute URLs everywhere.
Make sure baseUrl matches your production domain.
Make sure routes generate canonical paths.
Use consistent trailing slash rules.
Do not generate multiple conflicting schemas for the same entity.
Use [at]id consistently when you want to connect entities.
Make sure date strings are valid ISO 8601.
Make sure images are accessible and indexable.
Make sure logos are high quality and stable.
Provide sameAs links that are official.
Avoid placeholder values.
Avoid empty arrays.
Avoid injecting null schema.

Common mistakes and how this file avoids them

It only adds optional fields when they exist.
It maps arrays only when they have length.
It wraps Article image into an array.
It returns null for empty FAQ items.
It sets context and type explicitly.
It uses stable baseUrl.

Potential improvements you may consider

The JobPosting remote field is a string.
Some schema validators might expect a boolean or a different field.
If you see validation warnings, adjust accordingly.

The Organization founder field is a string.
Schema.org often allows Person or Organization.
If you need richer founder data, model it as a Person object.

The composable does not implement WebSite schema.
It uses Website type inside isPartOf.
If you want a full WebSite schema, add a generator.

The composable does not implement WebSite SearchAction.
If you have a site search, you can add it for sitelinks search box.

Testing structured data

After you inject JSON LD, test the page.
Use a structured data testing tool.
Validate that required fields exist.
Validate that URLs resolve.
Validate that language matches content.
Validate that breadcrumbs match navigation.
Validate that FAQ matches visible content.

Final summary

This module is a structured data factory.
It centralizes Schema.org JSON LD generation.
It supports multiple content types.
It supports localization aware URL helpers.
It supports breadcrumb automation.
Its SEO value comes from clarity.
Clarity supports richer understanding.
Richer understanding supports better presentation.

Appendix A Field by field quick reference

Organization

[at]context
[at]type
name
url
logo
alternateName
description
founder
foundingDate
foundingLocation
telephone
email
address PostalAddress
contactPoint ContactPoint array
sameAs array

WebPage

[at]context
[at]type
url
name
description
inLanguage
isPartOf Website
publisher Organization with logo ImageObject
mainEntity any schema object
datePublished
dateModified

BreadcrumbList

[at]context
[at]type
itemListElement ListItem array
ListItem position
ListItem name
ListItem item

RealEstateAgent

[at]context
[at]type
name
[at]id
url
image
telephone
email
priceRange
address PostalAddress
geo GeoCoordinates
openingHoursSpecification array
sameAs array
areaServed City

LocalBusiness

[at]context
[at]type
name
[at]id
url
image
telephone
priceRange
address PostalAddress
geo GeoCoordinates
openingHoursSpecification array
sameAs array

Service

[at]context
[at]type
serviceType
provider Organization
provider sameAs
areaServed Place
description
offers Offer
offers priceSpecification PriceSpecification

BlogPosting

[at]context
[at]type
mainEntityOfPage WebPage [at]id
headline
description
image
author Person name and url optional
publisher Organization with logo ImageObject
datePublished
dateModified

Article

[at]context
[at]type
mainEntityOfPage WebPage [at]id
headline
description
image array
author Person
publisher Organization with logo ImageObject
datePublished
dateModified
keywords

SoftwareApplication

[at]context
[at]type
name
applicationCategory
applicationSubCategory
description
url
operatingSystem
image
author Organization
offers Offer
aggregateRating AggregateRating
softwareVersion

JobPosting

[at]context
[at]type
title
description
identifier PropertyValue
datePosted
validThrough
employmentType
hiringOrganization Organization
jobLocation Place with PostalAddress
remote string
applicantLocationRequirements Country
baseSalary MonetaryAmount with QuantitativeValue
responsibilities
qualifications
skills
educationRequirements
experienceRequirements
incentiveCompensation
industry
jobBenefits

FAQPage

[at]context
[at]type
mainEntity Question array
Question name
acceptedAnswer Answer
Answer text

Appendix B Practical injection pattern

1 Generate the schema object.
2 JSON stringify it.
3 Inject it into a script tag in the page head.
4 Ensure the schema matches what users see.
5 Validate.
6 Monitor search console for enhancements.

Why 0.1 + 0.2 !== 0.3 Matters: Engineering Financial Precision in JS

Ahmed Niazy — Sat, 31 Jan 2026 12:01:40 +0000

Introduction:
Building a simple web app is easy. Building a mission-critical Enterprise Resource Planning (ERP) system that manages real money, real stock, and real business operations is an entirely different level of engineering. In this deep-dive, we are going to look behind the curtain of "Mehwar," a production-grade ERP system, to see how we solved the hardest challenges in JavaScript.

Part 1: The Floating Point Nightmare
The biggest mistake a junior developer makes is using native JavaScript arithmetic (+, -, *, /) for money. JavaScript uses IEEE 754 binary floating-point numbers. This means it cannot represent decimals like 0.1 or 0.2 exactly.

In "Mehwar," we solved this by never allowing raw math. Every calculation goes through a wrapper using Decimal.js.

Code Sample 1: Precise Tax Addition
function __add_percent(amount, percentage=0) {
var amount = parseFloat(amount);
var percentage = isNaN(percentage) ? 0 : parseFloat(percentage);

// We avoid (amount * (1 + percentage/100))
// Instead, we use controlled decimal steps:
var div = Decimal.div(percentage, 100).toNumber();
var mul = Decimal.mul(div, amount).toNumber();
return Decimal.add(amount, mul).toNumber();

}

Code Sample 2: Back-calculating from Tax-Inclusive Prices
If a product costs $115 including 15% VAT, how do you find the base price? Simple division (115 / 1.15) can lead to rounding drift.
function __get_principle(amount, percentage = 0, minus = false) {
var amount = parseFloat(amount);
var percentage = isNaN(percentage) ? 0 : parseFloat(percentage);
var mul = Decimal.mul(100, amount).toNumber();
var sum = minus
? Decimal.sub(100, percentage).toNumber()
: Decimal.add(100, percentage).toNumber();
return Decimal.div(mul, sum).toNumber();
}

Part 2: Real-Time UI Synchronization (The POS Engine)
The Point of Sale (POS) is the heart of an ERP. It must be fast, offline-capable, and handle complex logic every time a user presses a key.

Dynamic Event Binding:
We don't attach event listeners to every row. That would kill memory. Instead, we use event delegation on the table body.

Code Sample 3: Handling Quantity Changes in Real-time
$('table#pos_table tbody').on('change', 'input.pos_quantity', function () {
var entered_qty = __read_number($(this));
var tr = $(this).parents('tr');

// Advanced Check: Sales Rep Stock Allocation
var sales_rep_qty_available = tr.find('input.sales_rep_qty_available').val();
if (sales_rep_qty_available !== undefined && sales_rep_qty_available !== '') {
    var available_qty = parseFloat(sales_rep_qty_available);
    if (entered_qty > available_qty) {
        toastr.error('Insufficient stock in your van/allocation');
        __write_number($(this), available_qty > 0 ? available_qty : 0);
        entered_qty = available_qty > 0 ? available_qty : 0;
    }
}

// Recalculate everything for this row
pos_each_row(tr);
pos_total_row(); // Global total update

});

Part 3: The Search & Autocomplete Pipeline
When a user scans a barcode, they expect the product to appear in milliseconds. We use a heavily optimized jQuery UI Autocomplete flow.

Code Sample 4: Intelligent Product Search
$('#search_product').autocomplete({
source: function (request, response) {
var price_group = $('#price_group').val();
$.getJSON('/products/list', {
price_group: price_group,
location_id: $('input#location_id').val(),
term: request.term,
check_qty: 1
}, response);
},
minLength: 2,
select: function (event, ui) {
// Automatic stock validation before adding the row
if (ui.item.enable_stock != 1 || ui.item.qty_available > 0) {
pos_product_row(ui.item.variation_id);
} else {
alert('Out of stock!');
}
}
});

Part 4: Global Localization & Formatting Engine
An ERP must speak multiple "languages" (Currency, Date Formats, Thousands separators). In "Mehwar," we created a recursive conversion engine.

Code Sample 5: Recursive Currency Formatting
function __currency_convert_recursively(element) {
element.find('.display_currency').each(function() {
var value = $(this).text();
var show_symbol = $(this).data('currency_symbol');
var precision = $(this).data('is_quantity') ? __quantity_precision : __currency_precision;

    // Uses accounting.js for safe formatting
    $(this).text(accounting.formatMoney(value, __currency_symbol, precision, ...));
});

}

Part 5: User Experience (UX) for Professionals
Business users work in the system 8 hours a day. Micro-UX improvements are essential.

Data Persistence: We use a "Page Leave Confirmation" to prevent accidental data loss.
window.onbeforeunload = function() {
if (form_has_changed) {
return 'You have unsaved changes. Are you sure you want to leave?';
}
}
Visual Feedback: Numbers change color based on their value (Profit/Loss).
function __highlight(value, obj) {
obj.removeClass('text-success text-danger');
if (value > 0) obj.addClass('text-success');
else if (value < 0) obj.addClass('text-danger');
}

Part 6: Handling Massive DataTables
In an ERP, listing pages often handle tens of thousands of records. We use DataTables with Server-Side Processing for maximum performance.

Code Sample 6: Optimized DataTable Ajax Callback
function __datatable_ajax_callback(data){
for (var i = 0, len = data.columns.length; i < len; i++) {
// We strip unnecessary data from the request to save bandwidth
if (! data.columns[i].search.value) delete data.columns[i].search;
if (data.columns[i].searchable === true) delete data.columns[i].searchable;
if (data.columns[i].orderable === true) delete data.columns[i].orderable;
}
delete data.search.regex;
return data;
}

Part 7: The Modular Plugin System
Instead of loading every library on every page, we use an on-demand initialization strategy.

Code Sample 7: Dynamic TinyMCE Initialization
function init_tinymce(editor_id) {
tinymce.init({
selector: 'textarea#' + editor_id,
plugins: ['advlist autolink link image lists print preview table'],
toolbar: 'undo redo | styleselect | bold italic | alignleft aligncenter | bullist numlist',
menubar: 'favs file edit view insert format tools table help'
});
}

Part 8: Advanced Stock Management Logic
Stock calculations must happen on the client-side for immediate feedback, but must match the backend logic exactly.

Code Sample 8: Unit Multiplier Logic
function __getUnitMultiplier(row){
multiplier = row.find('select.sub_unit').find(':selected').data('multiplier');
return (multiplier == undefined) ? 1 : parseFloat(multiplier);
}

// When the unit changes, we must recalculate the entire row
$(document).on('change', 'select.sub_unit', function(){
var tr = $(this).closest('tr');
var multiplier = __getUnitMultiplier(tr);
// Logic to update unit price and stock availability based on multiplier
});

Part 9: Error Handling and Resilience
When an AJAX call fails (e.g., internet cutout), we must ensure the user doesn't lose data.

Code Sample 9: Safe Submit Button Handling
function __disable_submit_button(element) {
// We only disable the button if the user is confirmed to be online
if (window.navigator.onLine) {
element.attr('disabled', true);
element.html(' Processing...');
} else {
toastr.error('You are currently offline. Please check your connection.');
}
}

Part 10: State Management without Redux/Vuex
In a legacy-enhanced jQuery environment, we use the DOM itself as our state. This is highly performant for specialized UI like the POS.

// Our "State" is stored in data-attributes on the rows
//

function sync_state_to_ui(row_id) {
var tr = $('tr[data-row-id="' + row_id + '"]');
var qty = tr.data('quantity');
var price = tr.data('price');
var total = qty * price;
tr.find('.total-display').text(total);
}

Part 11: Real-time Date and Time Context
ERP systems rely heavily on "when" things happened. We use Moment.js to make these relative and human-readable.

Code Sample 10: Humanizing Dates Recursively
function __show_date_diff_for_human(element) {
moment.locale(app_locale);
element.find('.time-to-now').each(function() {
var string = $(this).text();
$(this).text(moment(string).toNow(true));
});
}

Summary:
Building a high-performance ERP requires more than just knowing a language; it requires understanding the domain (Finance, Inventory) and translating that into rock-solid, precise code. By mastering floating-point math, DOM-based state management, and localized formatting, you create a product that can run a multi-million dollar business without missing a single penny.

Conclusion:
This guide only scratches the surface. Deep-level engineering is found in the edge cases—the offline notifications, the recursive currency conversions, and the millisecond optimizations in search. Keep building, keep measuring, and never settle for "good enough" when money is on the line.

SoftwareEngineering #ProjectMehwar #FullStack #EnterpriseApp #JavaScriptMagic #Fintech #SystemArchitecture

TypeScript-First API Design: Building Type-Safe Systems at Enterprise Scale

Ahmed Niazy — Sat, 31 Jan 2026 11:28:20 +0000

TypeScript-First API Design: Building Type-Safe Systems at Enterprise Scale

1. Introduction – Why TypeScript Is the Foundation of Safe APIs

At small scale, JavaScript feels liberating. You can move fast, prototype quickly, and ship features with minimal friction. But as systems grow—more teams, more services, more integrations—JavaScript’s flexibility becomes its greatest liability. Nowhere is this more apparent than at system boundaries, especially APIs.

JavaScript Fails at Boundaries

APIs are contracts between independently evolving systems. Frontend teams, backend teams, mobile clients, third-party integrators—each moves at a different pace. JavaScript offers no native mechanism to enforce that these parties agree on data shapes, required fields, or error semantics.

Most production API failures are not caused by complex business logic. They are caused by:

Missing fields
Renamed properties
Incorrect nullability assumptions
Misinterpreted response shapes
Silent breaking changes

These are type mismatches, not algorithmic errors.

JavaScript discovers these mistakes only at runtime, often in production.

The Cost of Runtime Errors at Scale

In enterprise systems, runtime API errors are expensive:

🔥 Incidents triggered by a single malformed payload
🧯 Emergency hotfixes across multiple services
📉 Lost trust between teams
🕰️ Weeks of defensive coding and regression testing
😓 Engineers afraid to refactor

When a system grows large enough, fear becomes the bottleneck.

TypeScript Is Not “Types on Top of JavaScript”

This is the most common misunderstanding.

TypeScript is not merely JavaScript with annotations. It is:

A compile-time reasoning engine
A constraint system for design
A language for expressing invariants
A tool for enforcing correctness before code runs

In other words, TypeScript is a design tool.

Compile-Time Guarantees vs Runtime Failures

Runtime failures are discovered:

Late
By users
Under load
In environments you cannot reproduce

Compile-time failures are discovered:

Immediately
By the compiler
During development
Before merge or deploy

Every error shifted from runtime to compile time is a permanent cost reduction.

APIs as Type Contracts, Not JSON Documents

Traditional API design revolves around:

OpenAPI specs
Swagger docs
Markdown contracts

These are descriptive, not enforceable.

TypeScript enables something fundamentally different:

APIs as executable, enforceable type contracts

If your API contract is a TypeScript type, then:

Breaking changes fail builds
Consumers are updated automatically
Refactoring becomes safe
Documentation is always correct

This article explores how to design APIs where TypeScript is the primary source of truth, and everything else is derived from it.

2. TypeScript as an API Design Language

When you adopt a TypeScript-first mindset, APIs stop being “routes returning JSON” and start being typed interfaces between systems.

Endpoints as Typed Functions

Conceptually, every API endpoint can be modeled as a function:

(request: RequestType) => ResponseType

This framing is powerful because it aligns perfectly with TypeScript’s strengths.

Input types define what is allowed
Output types define what is guaranteed
Errors define what can go wrong

Requests as Input Types

Request types are not implementation details. They are contracts.

A well-designed request type:

Prevents invalid states
Encodes business rules
Forces explicit handling of optionality

Responses as Output Types

Response types define:

What consumers can rely on
Which fields are stable
Which fields are nullable or optional

This dramatically reduces defensive coding on the consumer side.

Errors as Explicit Unions

In JavaScript, errors are often strings, thrown exceptions, or undocumented shapes.

In TypeScript-first APIs, errors are first-class types:

type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError }

The compiler now enforces that errors are handled.

Interfaces vs Type Aliases

Understanding the difference matters at scale.

Interfaces:

Extendable
Open for declaration merging
Ideal for public, extensible contracts

Type aliases:

More expressive
Support unions and intersections
Ideal for precise modeling

Enterprise guideline:

Use interfaces for stable public DTOs
Use type aliases for composition and logic

Structural Typing: The Hidden Superpower

TypeScript is structurally typed, not nominally typed.

This means compatibility is based on shape, not explicit inheritance.

Why this matters for APIs:

Independent teams can conform to contracts without shared base classes
Mocking and testing are trivial
Refactoring internals does not break consumers

Structural typing enables loose coupling with strong guarantees.

Optional vs Required Properties

Optionality is not cosmetic. It encodes business meaning.

email?: string   // may be absent
email: string | null // explicitly empty

TypeScript forces teams to decide and document intent.

Readonly API Contracts

API contracts should be immutable:

interface UserDTO {
  readonly id: string
  readonly email: string
}

This prevents accidental mutation and communicates intent clearly.

Why `any` Breaks the Entire System

any is not a shortcut. It is a type system escape hatch.

Once any enters your API boundary:

Compile-time guarantees collapse
Consumers lose safety
Errors propagate silently

In enterprise systems, any is a design failure, not a convenience.

3. Modeling API Requests with TypeScript Types

APIs accept data from the outside world. That data is hostile by default.

TypeScript allows you to model exactly what your API accepts.

Typing Query Parameters

Query parameters are strings at runtime, but semantically richer.

Instead of:

page?: string

Use:

interface GetUsersQuery {
  page?: number
  pageSize?: number
  status?: 'active' | 'disabled'
}

This enables:

Compile-time validation
Automatic narrowing
IDE autocomplete

Typing Path Parameters

Path parameters often encode identity:

interface UserPathParams {
  userId: UserId
}

Using branded types:

type UserId = string & { readonly brand: unique symbol }

prevents accidental misuse across domains.

Typing Request Bodies

Request bodies represent intent.

For example, creating an order:

interface CreateOrderRequest {
  customerId: CustomerId
  items: ReadonlyArray<{
    productId: ProductId
    quantity: number
  }>
}

This prevents:

Missing fields
Invalid nesting
Implicit assumptions

Preventing Invalid States

TypeScript excels at making invalid states unrepresentable:

type PaymentMethod =
  | { type: 'card'; cardToken: string }
  | { type: 'paypal'; paypalId: string }

The compiler now enforces correctness.

Automatic Type Narrowing

Control flow analysis ensures safety:

if (req.type === 'card') {
  req.cardToken // guaranteed
}

No runtime checks needed.

Excess Property Checks

TypeScript rejects extra fields in object literals:

createUser({ email: 'a@b.com', role: 'admin', hack: true }) // ❌

This is a huge API safety net often overlooked.

4. DTOs as TypeScript Contracts (Not Backend Models)

DTOs (Data Transfer Objects) are not database entities. They are public contracts.

DTOs as Exported Public Types

DTOs define what the outside world sees:

export interface UserDTO {
  id: string
  email: string
  createdAt: string
}

Everything else is internal.

DTOs Are the API Surface

Changing a DTO is a breaking change.

TypeScript makes this visible immediately across all consumers.

Database Types vs Domain Types vs DTOs

Database types: persistence-focused
Domain types: business-logic-focused
DTOs: consumer-focused

They should never be the same.

Hiding Internal Complexity

DTOs flatten, normalize, and simplify:

// Domain
User {
  profile: { email, preferences, flags }
}

// DTO
UserDTO {
  id
  email
}

TypeScript enforces this separation.

Enforcing Backward Compatibility

When DTOs are types, removing a field breaks builds—not production.

This enables:

Safe deprecations
Gradual migrations
Versioned APIs

Contract-Driven Development with TypeScript

You can design the DTO before implementation.

The compiler ensures the implementation conforms.

5. Mapping API Responses Using TypeScript

APIs consume untrusted data.

The Core Problem

External data is:

Untyped
Unvalidated
Potentially malicious

TypeScript treats this correctly as unknown.

Unknown Until Proven Otherwise

const data: unknown = fetch(...)

This forces validation and transformation.

Mapping to Typed Domain Objects

Instead of trusting shapes, map explicitly:

function mapUser(raw: unknown): User {
  // validate + transform
}

Once mapped, the rest of the system is safe.

Transforming Types Safely

Mapping is where:

Dates become Date
IDs become branded types
Optional fields are normalized

Guaranteeing Internal Consistency

TypeScript ensures that after mapping:

No undefined surprises
No missing fields
No invalid states

This isolates risk to the boundary.

6. Type-Safe Error Modeling in TypeScript

Errors are part of the contract.

Union Types for Success and Failure

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E }

This forces handling.

Discriminated Unions

type ApiError =
  | { code: 'NOT_FOUND' }
  | { code: 'UNAUTHORIZED' }

The compiler knows all cases.

Error Codes as Literal Types

String literals prevent typos and drift.

Exhaustive Checking with `never`

switch (error.code) {
  case 'NOT_FOUND': ...
  default:
    const _exhaustive: never = error
}

If a new error is added, the compiler flags every missing handler.

Why Strings Are Not Error Handling

Strings:

Are not enumerable
Are not enforced
Drift silently

Types make errors predictable.

7. Runtime Validation and TypeScript Boundaries

The Fundamental Limitation

TypeScript types do not exist at runtime.

This is not a flaw—it is a design choice.

Schemas as the Bridge

Schema validation connects runtime data to compile-time types.

Zod (TypeScript-First)

Strengths:

Infers types from schemas
Excellent DX
Strong alignment with TS mental model

Ideal for TS-heavy systems.

Yup (Less Type-Driven)

Weaker inference
More runtime-oriented
Leads to duplication in large systems

io-ts (Advanced, Functional)

Extremely powerful
Steep learning curve
Best for FP-heavy teams

Single Source of Truth

Best practice:

Define schema
Infer TypeScript type
Reuse everywhere

No duplication. No drift.

8. Shared TypeScript Types Across Backend and Frontend

TypeScript enables end-to-end type safety.

Monorepos

Shared packages eliminate contract drift.

Shared Contracts Packages

@company/api-contracts

Contains:

DTOs
Error types
Enums

Versioned Exports

Semantic versioning applies to types too.

Breaking changes are explicit.

Enforced Alignment Across Teams

When the backend changes:

Frontend builds fail
Mobile builds fail
Integrations fail early

This is a feature.

When Sharing Types Is Good

Internal platforms
Unified orgs
Shared release cadence

When It Creates Tight Coupling

Public APIs
External consumers

TypeScript enforces correctness—but architecture still matters.

9. Common TypeScript Anti-Patterns in API Design

Overusing Generics

Generics add power but reduce readability.

Avoid generic abstractions that only one team understands.

Type-Level Overengineering

If your types require a whiteboard, they will be misused.

Types should clarify intent, not impress.

Exporting Internal Types

Leaking domain or DB types creates accidental coupling.

DTOs only.

Misusing `unknown`

unknown is a boundary, not a destination.

Validate and convert immediately.

Treating TypeScript as Documentation Only

If types are optional, ignored, or bypassed—TypeScript is wasted.

The compiler must be allowed to say no.

10. Conclusion – TypeScript as an Enterprise Tool

TypeScript is not a convenience layer.

It is:

A system design language
A contract enforcement engine
A scalability multiplier

When APIs are designed with TypeScript first:

Correctness becomes default
Refactoring becomes safe
Teams move faster with confidence
Systems scale without fear

The compiler becomes a teammate—one that never gets tired and never misses edge cases.

If TypeScript is optional in your API design, correctness is optional too.

At enterprise scale, that is a risk no serious system can afford.

Stop Rebuilding Editors: One Rich Text Editor for Every Framework

Ahmed Niazy — Fri, 23 Jan 2026 22:51:16 +0000

🌍 Introducing editor-elsolya — A Universal Rich Text Editor for the Modern Web

After working across multiple frontend stacks, one problem kept coming back again and again:

Why do we still need a different editor for every framework?

Today, I’m excited to introduce editor-elsolya — a framework-agnostic Rich Text Editor, built as a Web Component, designed to run everywhere the web runs.

🚀 One Editor. Every Framework.

Install once:

npm i editor-elsolya

Use anywhere:

No wrappers. No framework lock-in. No compromises.

🧠 Why Web Components?

editor-elsolya is built as a native Web Component, which means:

✅ Works with React, Vue, Angular, Nuxt, Next, Svelte, Solid, Astro, and Vanilla JS

✅ Uses standard HTML & DOM APIs

✅ Zero dependency on framework internals

✅ Safe for SSR environments (Next.js / Nuxt)

✅ Future-proof by web standards, not libraries

✨ Core Features

📝 Rich Text Editing powered by contenteditable

🧩 Native Custom Element:

🔁 Two-way data flow

Get / set content via value

Listen to changes via native CustomEvent

⚡ Instant integration — no config required

🔒 Framework-independent architecture

🧠 Optional Adapters

React adapter (editor-elsolya/react)

Vue adapter with v-model support (editor-elsolya/vue)

🖥 SSR-friendly

Runs only in the browser

Safe imports on the server

🎯 TypeScript-ready

🪶 Lightweight & performant

🔌 API Overview

value: string → get / set editor HTML

disabled: boolean → enable / disable editing

Event: change

e.detail.html

Pure DOM. No framework magic.

🏗 Built for Real-World Teams

This editor is ideal for:

Teams maintaining multiple frontend stacks

Design systems & shared UI libraries

Micro-frontend architectures

SaaS platforms with evolving tech stacks

Anyone tired of rewriting editors for every framework

🛠 Architecture Highlights

Built on native Web Platform APIs

No heavy editor engines

No hidden global state

Easy to extend (toolbar, themes, plugins)

Designed for long-term maintainability

🔮 Roadmap

Coming next:

🎨 Theme & CSS variables

🖼 Image upload support

🔌 Plugin system

⚙️ Configurable toolbar

📦 Smaller bundle & tree-shaking

🤝 Open Source

This project is open for feedback, ideas, and contributions.

If you care about clean architecture, web standards, and developer experience, I’d love to hear your thoughts.

🔗 Get started

npm i editor-elsolya

One editor.

Every framework.

Built on web standards.

https://www.npmjs.com/package/editor-elsolya
لو المقاله عجبتك ممكن تدعمني هنا
https://www.linkedin.com/posts/ahmed-niazy-maher-gad-elsolya-506507394_webcomponents-javascript-typescript-activity-7420592395328614400-RTzA?utm_source=share&utm_medium=member_desktop&rcm=ACoAAGDlLhYBuSmwE3MG1I6cEGDf7QWvWr7KXcw

WebComponents #JavaScript #TypeScript #FrontendDevelopment

Frontend #WebDev #NPM #OpenSource

React #Vue #Angular #Nuxt #NextJS #Svelte #Astro

MicroFrontends #DesignSystems #SSR

DeveloperExperience #SoftwareEngineering

ContentEditable #UIComponents #BuildInPublic

Stop Using JS for CSS

Ahmed Niazy — Mon, 08 Dec 2025 06:38:52 +0000

⭐ Stop Using JS for CSS — Deep, Detailed Explanation (Pure JS)

🔥 The Core Idea

JavaScript should not be used to control layout, styling logic, spacing, colors, animations, or responsiveness — CSS is already optimized for these tasks and is handled directly by the browser engine (e.g., Chrome’s Blink, Safari’s WebKit).

JavaScript should only control state.
CSS should control style.

Whenever JS tries to handle style, you get:

lower performance
layout thrashing
hard-to-maintain code
more bugs
loss of browser optimizations

Let’s break down the article's arguments in detail, with pure JavaScript examples.

🧩 Why CSS Should Handle Style (Not JavaScript)

### 🔹 1. CSS handles layout & rendering natively

Browsers have an optimized rendering engine designed specifically to handle:

layout
box models
animations
transitions
media queries
responsiveness

CSS runs on the Compositor Thread, not the Main JS Thread.
This means CSS can animate smoothly even at 60fps while JS is doing heavy work.

When you try to animate or style using JS, everything is forced into the Main Thread, leading to jank and lag.

🚫 JS for styling causes problems

Let’s go through the article’s main problems explained in depth.

⚠️ Problem 1 — JavaScript re-renders are expensive

Changing styles with JS often forces layout recalculation, which is one of the most expensive operations in a browser.

Example of bad practice:

element.style.width = "200px";
element.style.height = "300px";
element.style.marginTop = "20px";

Every line here may force the browser to calculate new layout.

⚠️ Problem 2 — JavaScript overrides browser optimizations

CSS has built-in optimizations:

cascade
inheritance
layered styles
GPU acceleration
parallel execution

When JS sets styles directly, these optimizations are bypassed.

Example:

// BAD
box.style.transform = "translateX(100px)";

Instead:

.move {
  transform: translateX(100px);
}

box.classList.add("move");

Much faster and cleaner.

⚠️ Problem 3 — Mixed responsibilities → unreadable code

JS is for logic, CSS is for styling.

When devs mix both in JS files, code becomes:

harder to read
harder to debug
harder to maintain
harder for teams

Example of the bad pattern:

const button = document.querySelector("button");
button.style.background = "#4CAF50";
button.style.padding = "12px";
button.style.borderRadius = "10px";

CSS should handle this:

.btn {
  background: #4CAF50;
  padding: 12px;
  border-radius: 10px;
}

button.classList.add("btn");

⚠️ Problem 4 — Losing progressive enhancement

If styling is tied to JS, and JS fails to load, the website breaks visually.

HTML + CSS should render correctly even without JS.

If your UI depends on JS to set colors, sizes, spacing… then your site has no fallback.

⚠️ Problem 5 — JS styling breaks caching

Browsers cache CSS files.
They do not cache inline JS-generated styles.

If you rely on JS for layout, the browser must recalculate everything from zero every reload.

⚠️ Problem 6 — Difficulty overriding styles

CSS offers:

!important
specificity
layered cascades
theming

But when JS injects styles inline:

<div style="color: red"></div>

You cannot override them from CSS easily.

⚠️ Problem 7 — JS animations are slower

JS animation loops like:

setInterval(() => {
  box.style.left = box.offsetLeft + 2 + "px";
}, 16);

This forces layout reflow every 16ms.

CSS animations:

@keyframes slide {
  0% { transform: translateX(0); }
  100% { transform: translateX(200px); }
}

.box {
  animation: slide 1s linear;
}

CSS animations run on the GPU → smooth.

🌟 **What JS should do instead**

🔸 1. Control state

JS handles state changes only.

Example:

box.classList.toggle("is-open");

CSS handles the style:

.box {
  height: 0;
  overflow: hidden;
  transition: height .3s ease;
}

.box.is-open {
  height: 200px;
}

🌟 Pure JavaScript Examples (Correct Way)

### Example 1 — Toggle menu

❌ Bad (JS controls styles):

menu.style.display = menu.style.display === "none" ? "block" : "none";

✔️ Good (JS controls state):

menu.classList.toggle("open");

#menu {
  display: none;
}

#menu.open {
  display: block;
}

### Example 2 — Dark mode

❌ Bad:

document.body.style.background = "#000";
document.body.style.color = "#fff";

✔️ Good:

document.body.classList.add("dark");

.dark {
  background: #000;
  color: #fff;
}

### Example 3 — Animate element

❌ Bad:

let pos = 0;
setInterval(() => {
  pos++;
  box.style.left = pos + "px";
}, 10);

✔️ Good:

box.classList.add("slide");

.slide {
  animation: move 2s linear forwards;
}

@keyframes move {
  from { transform: translateX(0); }
  to   { transform: translateX(200px); }
}

🌟 Conclusion (Very Important)

The article’s main message:

Use JavaScript for:

state
events
data
logic

Use CSS for:

layout
spacing
colors
themes
animations
responsiveness
transitions

Because CSS is faster, cleaner, and built exactly for this purpose — while JS slows down the browser and increases complexity when used for styling.

Mastering SSR, Data Fetching, and No-JavaScript Rendering in Nuxt 4

Ahmed Niazy — Fri, 05 Dec 2025 22:58:53 +0000

1. Introduction

Nuxt 4 is an incredibly powerful framework, especially with its SSR-first architecture powered by Nitro 4. However, many developers run into a frustrating issue:

Skeleton loaders remain visible forever, and real data never appears—especially when JavaScript is disabled.

This article is a complete deep-dive into:

How Nuxt 4 handles SSR
Why some pages fail when JavaScript is disabled
Why skeletons get stuck
How to design fully SSR-compatible pages
Debugging strategies
Correct use of useFetch()
Architecture best practices
Avoiding hydration pitfalls

This guide is based on real production problems and real solutions.

2. Understanding SSR in Nuxt 4

Nuxt 4 uses Nitro 4 for rendering.
SSR means:

The server renders the page.
useFetch() runs on the server.
HTML is generated with data already included.
Browser receives a fully rendered page.
If JS is enabled, hydration happens.

If JavaScript is disabled, the page should still display complete content — if SSR is implemented correctly.

3. The Root Cause of Skeleton Loaders Never Disappearing

If your data fetching happens only on the client, you will see:

Skeleton forever
No real content
Empty state
Hydration errors

Most commonly caused by:

onMounted(async () => {
  data.value = await $fetch('/api/data')
})

onMounted() never runs on the server, so SSR produces no content.

4. Client-Side Fetching vs Server-Side Fetching

❌ Client-side only:

onMounted(async () => {
  data.value = await $fetch('/api/data')
})

✔ Server-side rendering with useFetch():

const { data, pending } = await useFetch('/api/data', {
  server: true
})

Server fetching ensures:

Data loads before HTML is delivered
Skeleton disappears automatically
Page works without JavaScript

5. How Skeleton Loaders Work Internally

Nuxt skeleton loaders depend on pending.

<template>
  <Skeleton v-if="pending" />
  <Content v-else />
</template>

If pending stays true, skeleton never leaves.

Reasons:

useFetch executes on the client
Hydration mismatch
Data not fetched before SSR
Wrong composable structure

6. Fixing Skeleton Issues With SSR-First Fetching

Correct SSR-fetching:

await useFetch('/api/data', {
  server: true,
  lazy: false
})

Why these options matter:

server: true: forces SSR execution
lazy: false: ensures fetch runs immediately

7. The Architecture Mistake: Fetching Data Inside Components

Avoid this:

<!-- inside a component -->
<script setup>
const { data } = useFetch('/api/data')
</script>

This breaks SSR because:

Each component re-fetches
Execution happens after hydration
SSR doesn’t know about the data

Correct pattern:

Fetch at the page level
Pass data as props

8. Building SSR-Compatible Composables

Bad composable:

export const useItems = () => useFetch('/api/items')

Correct composable:

export const useItems = () => {
  return useFetch('/api/items', {
    server: true,
    lazy: false
  })
}

9. Full SSR-Ready Page Example (Works Without JavaScript)

<script setup>
const { data: items, pending } = await useFetch('/api/items', {
  server: true,
  lazy: false
})
</script>

<template>
  <ItemSkeleton v-if="pending" />

  <div v-else>
    <ItemCard
      v-for="item in items"
      :key="item.id"
      :item="item"
    />
  </div>
</template>

This page:

Renders instantly
Works without JavaScript
Avoids hydration mismatch
Displays content on first paint

10. Understanding Hydration and Why It Breaks UI State

Hydration attaches Vue to SSR-rendered HTML.

Hydration fails when:

SSR and client outputs don’t match
State differs between server and client
Data shape changes
Skeleton conditions differ

When hydration breaks → UI becomes stuck in loading state.

11. Debugging SSR Problems Like a Pro

Technique 1: Disable JavaScript

If the page breaks → your SSR is not fully implemented.

Technique 2: Verify server execution

console.log("Is server?", process.server)

Technique 3: Check Nuxt DevTools

View SSR state flow.

Technique 4: View page source

If HTML doesn’t contain data → SSR didn’t run fetch.

12. Why useFetch() Sometimes Runs on the Client Only

Common reasons:

Key function depends on client-side values
Conditional rendering prevents SSR execution
Missing options: server: true
Using watchers to trigger fetch

Wrong pattern:

const id = ref(null)
useFetch(() => `/api/item/${id.value}`)

SSR does not know id.

13. Nitro’s Role in SSR Data Handling

Nitro handles:

Server file execution
API routing
Caching
Lazy loading
Edge deployments

Understanding Nitro helps prevent:

Unnecessary client-fetches
Wrong caching behavior
Inconsistent SSR render

14. API Response Design for SSR Stability

Good SSR-friendly API example:

export default defineEventHandler(() => {
  return {
    success: true,
    data: [
      { id: 1, title: "Example A" },
      { id: 2, title: "Example B" }
    ]
  }
})

Guidelines:

Consistent keys
Predictable object structures
Avoid deeply nested unpredictability

15. Avoid Suspense Pitfalls

Suspense can break SSR.

❌ Wrong:

<Suspense>
  <ChildComponent />
</Suspense>

If child fetches → fallback shows forever when JS is disabled.

✔ Correct:

<Suspense>
  <ServerRenderedBlock />
  <template #fallback>
    <Skeleton />
  </template>
</Suspense>

16. Managing Large Component Trees in SSR

Rules:

Fetch data only once (at page level)
Pass ready data downward
Avoid client-side lifecycle hooks for initial load
Make components stateless regarding initial data

17. Performance Benefits of SSR-First Design

SSR-first yields:

Faster LCP
Better SEO
Fully visible first paint
No empty content
Smooth hydration
Better performance on slow devices
Works without JavaScript entirely

18. SSR Testing Checklist

✔ Disable JavaScript
✔ Check HTML source for real data
✔ Ensure skeleton disappears
✔ Ensure no hydration warnings
✔ Confirm fetch runs on server
✔ Validate composables return SSR data

19. Best Practices Summary

Prefer SSR fetching always
Avoid data fetching inside components
Avoid onMounted for initial data
Use composables sensibly
Ensure skeleton logic depends on SSR pending
Test pages with JS disabled
Ensure API responses are predictable
Avoid hydration mismatches

20. Final Exam (Great for Dev.to Readers)

Q1: Why do skeleton loaders remain visible when JavaScript is disabled?

Q2: Convert this into SSR-compatible code:

onMounted(async () => {
  list.value = await $fetch('/api/list')
})

Q3: Write an SSR-first composable using useFetch.

Q4: Describe what causes hydration mismatch errors.

Q5: Build a skeleton fallback pattern that works without JavaScript.

Conclusion

SSR in Nuxt 4 is powerful — but only when you understand how to use it correctly.
By adopting an SSR-first architecture, eliminating client-only data fetching, designing stable composables, and structuring your UI for hydration safety, your application becomes:

Faster
More stable
SEO-optimized
Accessible
Fully functional with JavaScript disabled
Production-ready

This guide provides the deep technical understanding needed to achieve that level of reliability in Nuxt 4.

Optimize Like a Pro: Advanced JavaScript Memory Techniques for Large-Scale Projects

Ahmed Niazy — Wed, 03 Dec 2025 08:19:46 +0000

A Deep, Extended, Example-Packed Article

Managing memory properly in JavaScript is one of the most critical skills for building fast, stable, and scalable applications. Whether you're developing a complex frontend interface, a long-running SPA, a Node.js backend, or a real-time system, poor memory handling can cause slowdowns, UI freezes, increased RAM usage, or even total crashes.

JavaScript has automatic memory management through its garbage collector, but automatic does NOT mean perfect. Incorrect coding patterns will easily prevent the garbage collector from doing its job — resulting in memory leaks and wasted resources.

This article is a full deep dive, expanded far beyond the standard explanations, with plenty of examples, patterns, anti-patterns, best practices, and developer tests at the end.

🔥 1. Understanding How JavaScript Stores and Frees Memory

JavaScript uses:

Stack memory → for simple values (numbers, booleans, strings)
Heap memory → for objects, arrays, functions, DOM nodes
Garbage Collector (GC) → automatically frees memory that no longer has references

GC mainly uses mark-and-sweep:
Objects reachable from the global scope are “marked.” Anything unmarked gets removed.

But here’s the problem:

If you keep even ONE reference to an object, GC CANNOT remove it.

This is how memory leaks happen.

⚠️ 2. The Most Common Memory Leak Sources in JavaScript

Below are the patterns responsible for 90% of memory leaks developers face — with extended examples.

🚨 2.1. Forgotten Event Listeners

One of the biggest leak sources.

❌ Bad Example (Leak)

function createButton() {
  const btn = document.createElement("button");
  btn.textContent = "Click me";

  btn.addEventListener("click", () => {
    console.log("Button clicked");
  });

  document.body.appendChild(btn);

  // Later...
  document.body.removeChild(btn);  
  // BUT the event listener reference is STILL in memory
}

The button is removed from the DOM, but the closure created by the event listener remains in memory.

✅ Fixed Version

function createButton() {
  const btn = document.createElement("button");
  const handler = () => console.log("Button clicked");

  btn.addEventListener("click", handler);
  document.body.appendChild(btn);

  // Remove properly
  setTimeout(() => {
    btn.removeEventListener("click", handler);
    document.body.removeChild(btn);
  }, 5000);
}

🚨 2.2. Closures That Capture Large Data

Closures are powerful — but dangerous when they accidentally retain unnecessary data.

❌ Bad Example

function makeProcessor() {
  const bigArray = new Array(100000).fill("DATA");

  return function () {
    console.log(bigArray.length);
  };
}

const fn = makeProcessor();
// bigArray stays alive forever!

✅ Optimized Version

function makeProcessor() {
  let bigArray = new Array(100000).fill("DATA");
  const len = bigArray.length;

  bigArray = null; // release memory

  return function () {
    console.log(len);
  };
}

🚨 2.3. Global Variables That Keep Growing

Anything attached to window or global scope lives forever unless removed.

❌ Anti-pattern

window.cache = [];

function save(item) {
  window.cache.push(item);
}

This grows endlessly.

✅ Better

const cache = new WeakSet();

function save(item) {
  cache.add(item);
}

WeakSet entries disappear automatically once the object has no other references.

🚨 2.4. Large Arrays That Never Get Emptied

❌ Example

let list = [];

for (let i = 0; i < 50000; i++) {
  list.push({ index: i });
}

// Later...
list = []; // still might leak in some cases because references remain

✅ Safe Cleanup

list.length = 0; // clears elements in-place

🚨 2.5. DOM Nodes Stored in Arrays or Objects

❌ Bad Example

const elements = [];

function render() {
  const div = document.createElement("div");
  elements.push(div); // stored forever
}

✅ Clean Version

function render() {
  const div = document.createElement("div");
  // Don't store DOM nodes globally unless necessary
}

⚡ 3. Advanced Memory Optimization Techniques

Now we go deeper — these are techniques used in high-performance applications, games, dashboards, and real-time apps.

🎯 3.1. Object Pooling

Instead of creating/destroying objects repeatedly, reuse them.

Example: Particle System Without Pooling (Very Slow)

function createParticle() {
  return {
    x: 0,
    y: 0,
    speed: Math.random() * 5,
  };
}

function loop() {
  const particle = createParticle();
  // ...
}

Optimized With Pooling

class Pool {
  constructor(size) {
    this.pool = Array.from({ length: size }, () => ({ x: 0, y: 0, speed: 0, active: false }));
  }

  acquire() {
    return this.pool.find(p => !p.active) || null;
  }

  release(p) {
    p.active = false;
  }
}

const particlePool = new Pool(1000);

🎯 3.2. Using WeakMap and WeakSet for Caches

Perfect for metadata, temporary states, or per-object settings.

Example: Metadata Cache

const meta = new WeakMap();

function track(el, data) {
  meta.set(el, data);
}

function get(el) {
  return meta.get(el);
}

If el is removed from DOM → metadata gets garbage-collected automatically.

🎯 3.3. Debouncing and Throttling High-Frequency Events

Scrolling, mousemove, resizing → can create tons of allocations.

Example

window.addEventListener("scroll", throttle(updateUI, 200));

🎯 3.4. Avoiding Heavy Arrays With Mixed Types

Mixed arrays slow down the engine and increase memory usage.

❌ Mixed array

const arr = [1, "two", { three: 3 }];

✅ Use consistent type patterns

const arr = [1, 2, 3, 4];

🎯 3.5. Batch DOM Updates Instead of Repeated Rendering

❌ Bad

items.forEach(item => {
  const div = document.createElement("div");
  document.body.appendChild(div);
});

✅ Good

const frag = document.createDocumentFragment();

items.forEach(item => {
  const div = document.createElement("div");
  frag.appendChild(div);
});

document.body.appendChild(frag);

🧩 4. Memory-Safe Patterns for Large Applications

Below are patterns specifically for big apps:

🟢 4.1. Unsubscribe EVERYTHING When Components Unmount

For SPA frameworks:

Remove event listeners
Clear intervals
Clear timeouts
Cancel API calls
Close WebSocket connections
Remove observers (ResizeObserver, IntersectionObserver)

Example

let interval;

function mount() {
  interval = setInterval(() => console.log("running..."), 1000);
}

function unmount() {
  clearInterval(interval);
}

🟢 4.2. Split Big Data Into Chunks

Avoid loading massive data at once.

function processInChunks(data, chunkSize = 1000) {
  for (let i = 0; i < data.length; i += chunkSize) {
    const chunk = data.slice(i, i + chunkSize);
    console.log("Processing...", chunk.length);
  }
}

🟢 4.3. Lazy-Load Heavy Objects

Only create heavy objects when they are actually needed.

🧪 5. Developer Self-Test (English Questions)

Use these to test yourself or others.

📝 Section 1: Concept Questions

What is the difference between stack and heap memory in JavaScript?
Why can a single remaining reference prevent garbage collection?
What is a closure memory leak?
What is the benefit of WeakMap compared to Map?
How do event listeners contribute to memory leaks?

📝 Section 2: Code Analysis

Question 1

Will this cause a memory leak?

const data = new Array(50000).fill(1);

function log() {
  console.log("Hello");
}

setInterval(log, 1000);

Question 2

Where is the leak?

const store = [];

function add() {
  const el = document.createElement("div");
  store.push(el);
}

Question 3

Fix this:

function create() {
  const obj = { big: new Array(20000) };
  return () => console.log("Hi");
}

📝 Section 3: Practical Tasks

Create a function that safely clears an array containing thousands of objects.
Rewrite a caching system using WeakMap.
Build a simple object pool for reusing temporary objects.

How JavaScript Handles Memory Under the Hood — A Complete Deep Dive

Ahmed Niazy — Fri, 28 Nov 2025 23:26:19 +0000

JavaScript is often described as a “memory-safe” language because it includes a garbage collector, but this doesn’t mean memory problems magically disappear.
In reality, JS developers face memory leaks all the time — especially in:

Single-Page Applications (SPA)
Real-time dashboards
Long-lived Node.js servers
Complex React/Vue/Angular apps
Components with continuous DOM updates
Apps that keep state in memory for hours

To write robust, scalable, high-performance code, you must understand exactly how JavaScript memory works internally.
This article will take you from beginner to expert by exploring:

✔ Stack vs Heap

✔ Execution Contexts & Call Stack

✔ Primitive vs Reference values

✔ How JS allocates, uses, and releases memory

✔ Mark & Sweep garbage collection

✔ Modern garbage collectors (Generational GC, Incremental GC, Concurrent GC)

✔ All possible sources of memory leaks

✔ How to detect leaks using Chrome DevTools

✔ Advanced real-world examples

This is a complete deep dive, not just a simple explanation.

🧠 1. The Architecture of JavaScript Memory

JavaScript uses two fundamental memory regions:

┌─────────────────────────────────────┐
│               Stack                 │  → automatic, fast memory
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│                Heap                 │ → dynamic, slow memory
└─────────────────────────────────────┘

Let’s break them down in extreme detail.

🧱 2. Stack Memory — Fast, Predictable, Structured

The stack is a Last-In-First-Out (LIFO) memory system.

Push → Push → Push
← Pop ← Pop ← Pop

The stack stores:

✔ Primitive values

(numbers, strings, booleans, undefined, null, symbols, bigint)

✔ Function arguments

(even objects are passed as references stored in stack)

✔ Execution context

(local variables, this, scope chain)

✔ Return addresses

(where to go back after a function finishes)

✔ Pointers to heap objects

Example:

let a = 5;      // stored directly in stack
let b = a;      // copied by value

const obj = { name: "Alaa" };

Stack memory holds:

a → 5
b → 5
obj → (pointer to heap)

Heap memory holds:

{ name: "Alaa" }

🔥 3. Heap Memory — Dynamic, Flexible, Unpredictable

The heap is a large region used for objects, arrays, functions, closures, and anything dynamic.

Examples of heap allocation:

const user = { name: "Alaa", age: 25 };   // object → heap
const arr = [1, 2, 3];                    // array → heap
function foo() {}                         // function → heap

The heap is:

larger
slower
unstructured
requires garbage collection

🏗️ 4. How JavaScript Executes Code (Call Stack + Memory)

To fully understand memory behavior, you must understand the JavaScript execution model.

🌀 Each function call creates an "Execution Context"

Example:

function sum(a, b) {
  let result = a + b;
  return result;
}

sum(3, 5);

Execution context contains:

Lexical Environment
Variable Environment
this binding
Function arguments
Reference to outer environment

Example memory:

sum EC
├── a = 3  (stack)
├── b = 5  (stack)
└── result = 8 (stack)

🔄 5. Memory Lifecycle: Allocation → Usage → Release

1. Allocation

JS allocates memory automatically:

let x = 10;        // primitive → stack
let obj = {};      // reference → stack, object → heap

2. Usage

JS reads or modifies values:

obj.name = "Alaa";

3. Release

When values become unreachable, memory should be released.

But this is where problems begin…

🧹 6. Garbage Collection (Mark & Sweep) — Explained in Depth

JavaScript engines like V8 (Chrome, Node) use Mark & Sweep garbage collection.

✔ Step 1 – Mark Phase

Garbage collector identifies “root” objects:

Global object (window / global)
Active functions on the call stack
Closures
Variables referenced in scope chain

From roots, GC recursively marks all reachable objects.

Roots
  ├── A (reachable)
  │     └── B (reachable)
  └── C (unreachable) ❌

✔ Step 2 – Sweep Phase

Unmarked objects are removed from heap.

This prevents memory from growing indefinitely.

🚀 7. Modern Garbage Collectors (Full Professional Understanding)

V8 does not use just one algorithm.
It uses multiple GC systems working together:

✔ 1. Generational Garbage Collection

Heap is divided into:

Young generation → new small objects
Old generation → older, long-lived objects

New objects die young → cleaned quickly.
Old objects stay → cleaned slowly.

✔ 2. Incremental GC

Large GC operations are split into smaller parts to avoid freezing the UI.

✔ 3. Concurrent GC

GC runs in parallel with the main thread.

✔ 4. Compaction

Defragments memory to reduce fragmentation.

All of this happens automatically — but you can still break it.

⚠️ 8. All Types of Memory Leaks in JavaScript (Complete Guide)

Here are the real ways your app leaks memory.

🔥 8.1 Leak from Closures Retaining Large Data

This is one of the most dangerous leaks.

function create() {
  const hugeArray = new Array(1_000_000).fill("data");

  return function () {
    console.log("Using closure");
  };
}

const fn = create();

Even though the returned function does not use hugeArray,
the closure keeps the entire scope alive → leak.

GC cannot remove it because the closure is still reachable.

Fix:

Move large data outside closure or nullify after use.

🔥 8.2 Leaks from setInterval / setTimeout

setInterval(() => {
  console.log("Hi");
}, 1000);

If you never call:

clearInterval(id);

→ The closure stays in memory forever.

Even if the page changes.

🔥 8.3 Leaks from Event Listeners Not Removed

const btn = document.getElementById("btn");

btn.addEventListener("click", () => console.log("click"));

If you remove the element:

btn.remove();

The listener STILL exists unless removed:

btn.removeEventListener("click", handler);

🔥 8.4 Leaks from Global Variables

Common mistake:

leaked = "Hello"; // becomes window.leaked → never removed

🔥 8.5 Leaks from Forgotten DOM References

let div = document.getElementById("box");

document.body.removeChild(div);

// but:
console.log(div); // reference keeps it alive!

🔥 8.6 Leaks from Caches, Maps, WeakMaps

const cache = new Map();

function process(obj) {
  cache.set(obj, "processed");
}

If obj should be garbage collected, it won’t be — because it’s stored in a Map.

Fix:

Use WeakMap, not Map.

const cache = new WeakMap();

WeakMap keys do NOT prevent GC.

🌐 8.7 Leaks in Single Page Applications (SPA)

SPAs often leak memory due to:

components not fully destroyed
listeners not removed
intervals continuing across pages
references stored inside global state (Vuex, Redux)
images or canvas objects kept alive
virtual DOM nodes referencing removed elements

Angular, Vue, React apps suffer from this daily.

🔎 9. Detecting Memory Leaks Using Chrome DevTools (Step-by-Step Master Class)

Open:

Chrome → F12 → Performance or Memory

Tool 1 — Heap Snapshot

Shows:

detached DOM nodes
objects kept alive by closures
references preventing cleanup

Tool 2 — Allocation Timeline

Used to detect memory growth over time.

Tool 3 — Live Memory Graph

Used to track leak patterns.

What to Look For:

✔ Increasing heap after each user action
✔ Detached DOM nodes
✔ Event listeners not removed
✔ Large arrays in closures
✔ setInterval callbacks still active

A Real Test:

Take snapshot
Click around the page
Take another snapshot
Heap should return to the same level
If it grows each time → leak

🛠️ 10. Real-World Example: Leaking React Component

useEffect(() => {
  const id = setInterval(() => {
    console.log("running");
  }, 1000);

  return () => clearInterval(id); // cleanup
}, []);

If cleanup is missing → leak.

🛠️ 11. Real-World Example: Node.js Memory Leak

let cache = {};

function addUser(user) {
  cache[user.id] = user; // never removed
}

Over time (API server running for days), this kills memory.

Fix:

Use:

LRU Cache
TTL expiration
WeakMap

🧵 12. Advanced Example: Leaking Through Closures

function setup() {
  let bigObj = new Array(5_000_000).fill("hello");

  return function inner() {
    console.log("I keep bigObj alive");
  };
}

let fn = setup();

Even if you never use bigObj, it’s still reachable.

Fix: Clean it manually

function setup() {
  let bigObj = new Array(5_000_000).fill("hello");

  function inner() {
    console.log("I keep bigObj alive");
  }

  bigObj = null; // remove heavy reference

  return inner;
}

🏁 Final Thoughts — You Are Now an Expert

JavaScript tries to manage memory for you — but you can absolutely break it.

Key takeaways:

Stack → small, fast, structured
Heap → large, dynamic, messy
Execution context is the heart of JS memory
Closures can accidentally keep entire scopes in memory
setInterval, listeners, global vars → biggest leak sources
SPAs are at high risk of memory leaks
Chrome DevTools is your best friend
GC is smart — but not magic

Firebase Composables - قابلة لإعادة الاستخدام

Ahmed Niazy — Sun, 23 Nov 2025 21:15:37 +0000

Firebase Composables - قابلة لإعادة الاستخدام

هذه المجموعة من Composables تتيح لك استخدام Firebase بسهولة في أي مشروع Nuxt.js مع تغيير البيانات فقط.

📁 الملفات

1. `useFirebaseConfig.ts`

ملف التكوين الأساسي لـ Firebase - يحتوي على الإعدادات الافتراضية.

2. `useFirebaseCore.ts`

Composable أساسي لـ Firebase - يوفر الوظائف الأساسية للاتصال والخدمات.

3. `useFirebaseChat.ts`

Composable خاص بالمحادثات - يوفر وظائف المحادثات الفورية.

4. `useFirebaseNotifications.ts`

Composable خاص بالإشعارات - يوفر وظائف الإشعارات الفورية.

5. `useFirebaseExample.ts`

مثال على كيفية استخدام جميع Composables معاً.

📖 شرح تفصيلي للملفات

1. `useFirebaseConfig.ts` - ملف التكوين

هذا الملف يحتوي على جميع واجهات التكوين والإعدادات الافتراضية لـ Firebase.

الواجهات (Interfaces):

FirebaseConfig

واجهة تحتوي على جميع بيانات التكوين الأساسية لـ Firebase
الحقول المطلوبة:
- apiKey: مفتاح API الخاص بمشروع Firebase
- authDomain: نطاق المصادقة (مثل: your-project.firebaseapp.com)
- projectId: معرف المشروع
- storageBucket: حاوية التخزين
- messagingSenderId: معرف المرسل للإشعارات
- appId: معرف التطبيق
الحقول الاختيارية:
- measurementId: معرف القياس (لـ Google Analytics)

FirestoreConfig

واجهة لتكوين Firestore
الحقول:
- collectionPrefix: بادئة اختيارية لأسماء المجموعات
- subCollectionPrefix: بادئة اختيارية للمجموعات الفرعية

RealtimeConfig

واجهة لتكوين Realtime Database
الحقول:
- databaseURL: رابط قاعدة البيانات (مطلوب)
- pathPrefix: بادئة اختيارية للمسارات

MessagingConfig

واجهة لتكوين Cloud Messaging
الحقول:
- vapidKey: مفتاح VAPID للإشعارات
- defaultNotificationOptions: خيارات افتراضية للإشعارات (عنوان، أيقونة، شارة، صوت)

الدالة `useFirebaseConfig()`

ترجع كائن يحتوي على جميع الإعدادات الافتراضية
يمكن استخدامها مباشرة أو دمجها مع إعدادات مخصصة
الإعدادات الافتراضية قابلة للتعديل حسب احتياجات المشروع

2. `useFirebaseCore.ts` - Composable الأساسي

هذا الملف هو القلب الأساسي لجميع Composables الأخرى. يوفر الوظائف الأساسية لجميع خدمات Firebase.

الواجهات:

FirebaseCoreOptions

واجهة خيارات التكوين للـ Composable الأساسي
الحقول:
- config: تكوين Firebase الأساسي (مطلوب)
- firestoreConfig: تكوين Firestore (اختياري)
- realtimeConfig: تكوين Realtime Database (اختياري)
- messagingConfig: تكوين Cloud Messaging (اختياري)
- onAuthStateChanged: دالة callback عند تغيير حالة المصادقة
- onMessageReceived: دالة callback عند استلام رسالة push

الحالة (State):

app: مرجع لتطبيق Firebase
auth: خدمة المصادقة
firestore: خدمة Firestore
database: خدمة Realtime Database
messaging: خدمة Cloud Messaging
currentUser: المستخدم الحالي
isAuthenticated: حالة المصادقة (true/false)
isInitialized: حالة التهيئة
authLoading: حالة تحميل المصادقة

الوظائف الأساسية:

المصادقة (Authentication):

initializeFirebase(): تهيئة Firebase وربط جميع الخدمات
signInAnonymouslyUser(): تسجيل دخول مجهول
signInWithEmail(email, password): تسجيل دخول بالبريد الإلكتروني
signOutUser(): تسجيل الخروج

Firestore:

addDocument(collectionName, data): إضافة مستند جديد مع إضافة createdAt و updatedAt تلقائياً
updateDocument(collectionName, docId, data): تحديث مستند مع تحديث updatedAt تلقائياً
deleteDocument(collectionName, docId): حذف مستند
subscribeToCollection(collectionName, callback, constraints): الاشتراك في مجموعة مع دعم:
- where: فلاتر الاستعلام
- orderBy: ترتيب النتائج
- limit: تحديد عدد النتائج

Realtime Database:

setRealtimeData(path, data): تعيين بيانات في مسار معين مع إضافة timestamp تلقائياً
pushRealtimeData(path, data): إضافة بيانات جديدة مع توليد مفتاح تلقائي
updateRealtimeData(path, data): تحديث بيانات مع إضافة updatedAt تلقائياً
removeRealtimeData(path): حذف بيانات من مسار معين
subscribeToRealtimeData(path, callback): الاشتراك في التغييرات في مسار معين

Cloud Messaging:

requestNotificationPermission(): طلب إذن الإشعارات والحصول على token
subscribeToMessages(callback): الاشتراك في استقبال رسائل push

التنظيف:

cleanup(): تنظيف الموارد (يتم تلقائياً عند إغلاق التطبيق)

3. `useFirebaseChat.ts` - Composable المحادثات

هذا الملف يوفر وظائف كاملة لإدارة المحادثات الفورية مع دعم Firestore و Realtime Database.

الواجهات:

ChatMessage

واجهة تمثل رسالة محادثة
الحقول:
- id: معرف الرسالة
- body: نص الرسالة
- type: نوع الرسالة (text أو attachment)
- senderId: معرف المرسل
- senderName: اسم المرسل (اختياري)
- senderAvatar: صورة المرسل (اختياري)
- roomId: معرف الغرفة
- createdAt: تاريخ الإنشاء
- updatedAt: تاريخ التحديث
- isTemp: هل الرسالة مؤقتة (لـ Optimistic Updates)
- attachments: مصفوفة المرفقات (اختياري)

ChatRoom

واجهة تمثل غرفة محادثة
الحقول:
- id: معرف الغرفة
- name: اسم الغرفة (اختياري)
- participants: مصفوفة معرفات المشاركين
- lastMessage: آخر رسالة (اختياري)
- lastMessageAt: تاريخ آخر رسالة (اختياري)
- createdAt: تاريخ الإنشاء
- updatedAt: تاريخ التحديث

ChatOptions

واجهة خيارات المحادثات (تمتد من FirebaseCoreOptions)
الحقول الإضافية:
- useRealtime: استخدام Realtime Database بدلاً من Firestore
- collectionName: اسم المجموعة (افتراضي: chats)
- onNewMessage: callback عند استلام رسالة جديدة
- onMessageSent: callback عند إرسال رسالة
- onMessageError: callback عند حدوث خطأ
- onRoomCreated: callback عند إنشاء غرفة

الحالة (State):

جميع الحالات من useFirebaseCore
messages: مصفوفة الرسائل الحالية
rooms: مصفوفة الغرف
currentRoomId: معرف الغرفة الحالية
isSubscribed: حالة الاشتراك

الوظائف:

إدارة الغرف:

createRoom(participants, name): إنشاء غرفة محادثة جديدة
- participants: مصفوفة معرفات المستخدمين
- name: اسم الغرفة (اختياري)
- ترجع معرف الغرفة الجديدة

إرسال الرسائل:

sendMessage(roomId, body, type, attachments): إرسال رسالة عادية
sendMessageOptimistic(roomId, body, type, attachments): إرسال رسالة مع Optimistic Update
- تعرض الرسالة فوراً قبل تأكيد الإرسال من السيرفر
- تحذف الرسالة المؤقتة عند استلام الرسالة الحقيقية أو عند فشل الإرسال

الاشتراكات:

subscribeToRoom(roomId): الاشتراك في رسائل غرفة معينة
- تحدث messages تلقائياً عند وصول رسائل جديدة
- ترتيب الرسائل حسب وقت الإنشاء
subscribeToUserRooms(): الاشتراك في جميع غرف المستخدم الحالي
- تحدث rooms تلقائياً
- ترتيب الغرف حسب آخر رسالة

وظائف مساعدة:

createTempMessage(body, type, attachments): إنشاء رسالة مؤقتة
loadMessages(messages): تحميل رسائل يدوياً
clearMessages(): مسح جميع الرسائل
getCurrentUserId(): الحصول على معرف المستخدم الحالي

التنظيف:

cleanupChat(): تنظيف موارد المحادثات فقط
cleanupAll(): تنظيف جميع الموارد

4. `useFirebaseNotifications.ts` - Composable الإشعارات

هذا الملف يوفر وظائف كاملة لإدارة الإشعارات مع دعم Push Notifications.

الواجهات:

Notification

واجهة تمثل إشعار
الحقول:
- id: معرف الإشعار
- title: عنوان الإشعار
- message: نص الإشعار
- type: نوع الإشعار (info, success, warning, error)
- userId: معرف المستخدم (اختياري - للإشعارات الخاصة)
- data: بيانات إضافية (اختياري)
- read: حالة القراءة (true/false)
- createdAt: تاريخ الإنشاء
- updatedAt: تاريخ التحديث

NotificationOptions

واجهة خيارات الإشعارات (تمتد من FirebaseCoreOptions)
الحقول الإضافية:
- useRealtime: استخدام Realtime Database
- collectionName: اسم المجموعة (افتراضي: notifications)
- onNewNotification: callback عند استلام إشعار جديد
- onNotificationRead: callback عند قراءة إشعار
- onNotificationError: callback عند حدوث خطأ

الحالة (State):

جميع الحالات من useFirebaseCore
notifications: مصفوفة الإشعارات
unreadCount: عدد الإشعارات غير المقروءة (يُحسب تلقائياً)
isSubscribed: حالة الاشتراك

الوظائف:

إدارة الإشعارات:

createNotification(title, message, type, userId, data): إنشاء إشعار جديد
- title: عنوان الإشعار (مطلوب)
- message: نص الإشعار (مطلوب)
- type: نوع الإشعار (افتراضي: info)
- userId: معرف المستخدم (اختياري - إذا لم يُحدد يستخدم المستخدم الحالي)
- data: بيانات إضافية (اختياري)
- ترجع معرف الإشعار الجديد
markAsRead(notificationId): تمييز إشعار كمقروء
- تحدث unreadCount تلقائياً
markAllAsRead(): تمييز جميع إشعارات المستخدم كمقروءة
- تحدث جميع الإشعارات المحلية والسيرفر
deleteNotification(notificationId): حذف إشعار
- تحدث unreadCount تلقائياً

الاشتراكات:

subscribeToUserNotifications(): الاشتراك في إشعارات المستخدم الحالي فقط
- تحدث notifications تلقائياً
- ترتيب الإشعارات حسب تاريخ الإنشاء (الأحدث أولاً)
subscribeToGeneralNotifications(): الاشتراك في الإشعارات العامة (بدون userId)
- للإشعارات التي تظهر لجميع المستخدمين

Push Notifications:

initializePushNotifications(): تهيئة Push Notifications
- تطلب إذن الإشعارات من المتصفح
- ترجع token يمكن إرساله للسيرفر
subscribeToPushMessages(callback): الاشتراك في استقبال رسائل push
- يتم استدعاء callback عند استلام رسالة push

وظائف مساعدة:

getNotificationsByType(type): الحصول على إشعارات بنوع معين
getUnreadNotifications(): الحصول على جميع الإشعارات غير المقروءة
loadNotifications(notifications): تحميل إشعارات يدوياً
addNotification(notification): إضافة إشعار يدوياً (للاستخدام المحلي)
clearNotifications(): مسح جميع الإشعارات
updateUnreadCount(): تحديث عداد الإشعارات غير المقروءة
getCurrentUserId(): الحصول على معرف المستخدم الحالي

التنظيف:

cleanupNotifications(): تنظيف موارد الإشعارات فقط
cleanupAll(): تنظيف جميع الموارد

5. `useFirebaseExample.ts` - مثال الاستخدام

هذا الملف يحتوي على مثال كامل يوضح كيفية استخدام جميع Composables معاً في مشروع حقيقي.

البنية:

1. تكوين Firebase:

const firebaseConfig: FirebaseConfig = {
  // جميع بيانات التكوين
}

2. تهيئة Composables:

chatFirebase: instance من useFirebaseChat
notificationFirebase: instance من useFirebaseNotifications

3. وظائف مساعدة للمحادثات:

initializeChat(): تهيئة المحادثات والاشتراك في الغرف
joinChatRoom(roomId): الانضمام لغرفة محادثة
createChatRoom(participants, name): إنشاء غرفة جديدة
sendChatMessage(roomId, messageText): إرسال رسالة نصية
sendChatFile(roomId, fileName, fileType, fileUrl, fileSize): إرسال ملف

4. وظائف مساعدة للإشعارات:

initializeNotifications(): تهيئة الإشعارات والاشتراك
createNotification(title, message, type, userId, data): إنشاء إشعار
markNotificationAsRead(notificationId): تمييز إشعار كمقروء
markAllNotificationsAsRead(): تمييز الكل كمقروء
deleteNotification(notificationId): حذف إشعار

5. وظائف المصادقة:

signInAnonymously(): تسجيل دخول كضيف
signInWithEmail(email, password): تسجيل دخول بالبريد
signOut(): تسجيل الخروج

6. وظائف التنظيف:

cleanupAll(): تنظيف جميع الموارد
cleanupChat(): تنظيف موارد المحادثات فقط
cleanupNotifications(): تنظيف موارد الإشعارات فقط

القيم المُرجعة:

حالة المحادثات:

chatMessages: مصفوفة الرسائل
chatRooms: مصفوفة الغرف
chatCurrentRoom: معرف الغرفة الحالية
chatConnected: حالة الاتصال
chatInitialized: حالة التهيئة
chatLoading: حالة التحميل
chatSubscribed: حالة الاشتراك

حالة الإشعارات:

notifications: مصفوفة الإشعارات
unreadCount: عدد الإشعارات غير المقروءة
notificationConnected: حالة الاتصال
notificationInitialized: حالة التهيئة
notificationLoading: حالة التحميل
notificationSubscribed: حالة الاشتراك

حالة المستخدم:

currentUser: بيانات المستخدم الحالي

وظائف مساعدة:

getUnreadNotifications(): الحصول على الإشعارات غير المقروءة
getNotificationsByType(type): الحصول على إشعارات بنوع معين
getCurrentUserId(): الحصول على معرف المستخدم

مثال الاستخدام في المكون:

يحتوي الملف على مثال كامل في التعليقات يوضح كيفية:

استيراد واستخدام useFirebaseExample
تهيئة Firebase عند تحميل المكون
إرسال الرسائل والانضمام للغرف
إدارة الإشعارات
تنظيف الموارد عند إغلاق المكون

🔍 شرح تفصيلي مع أمثلة عملية

1. `useFirebaseConfig.ts` - شرح مفصل

الغرض من الملف:

هذا الملف يحتوي على جميع الواجهات (Interfaces) والإعدادات الافتراضية لـ Firebase. يعمل كملف مرجعي لتحديد أنواع البيانات المستخدمة في جميع الملفات الأخرى.

كيف يعمل:

// 1. تعريف الواجهات (TypeScript Interfaces)
export interface FirebaseConfig {
  apiKey: string;           // مفتاح API - يحصل عليه من Firebase Console
  authDomain: string;        // نطاق المصادقة
  projectId: string;        // معرف المشروع
  // ... إلخ
}

// 2. دالة ترجع الإعدادات الافتراضية
export const useFirebaseConfig = () => {
  const defaultConfig: FirebaseConfig = {
    apiKey: 'YOUR_FIREBASE_API_KEY',
    // ... إلخ
  };

  return {
    defaultConfig,
    defaultFirestoreConfig,
    defaultRealtimeConfig,
    defaultMessagingConfig
  };
};

مثال على الاستخدام:

import { useFirebaseConfig } from './useFirebaseConfig';

// الحصول على الإعدادات الافتراضية
const { defaultConfig } = useFirebaseConfig();

// دمج الإعدادات الافتراضية مع إعدادات مخصصة
const myConfig = {
  ...defaultConfig,
  apiKey: 'MY_ACTUAL_API_KEY',
  projectId: 'my-project-id'
};

ملاحظات مهمة:

جميع الحقول في FirebaseConfig مطلوبة ما عدا measurementId
يمكن استخدام FirestoreConfig لإضافة بادئات لأسماء المجموعات
RealtimeConfig يتطلب databaseURL فقط
MessagingConfig يحتوي على خيارات Push Notifications

2. `useFirebaseCore.ts` - شرح مفصل

الغرض من الملف:

هذا الملف هو الأساس لجميع Composables الأخرى. يوفر جميع الوظائف الأساسية لخدمات Firebase (Authentication, Firestore, Realtime Database, Messaging).

كيف يعمل خطوة بخطوة:

الخطوة 1: التهيئة

const initializeFirebase = () => {
  // 1. إنشاء تطبيق Firebase
  app.value = initializeApp(options.config);

  // 2. تهيئة الخدمات
  auth.value = getAuth(app.value);
  firestore.value = getFirestore(app.value);

  // 3. إعداد مستمع حالة المصادقة
  onAuthStateChanged(auth.value, (user) => {
    currentUser.value = user;
    isAuthenticated.value = !!user;
  });
};

الخطوة 2: المصادقة

// تسجيل دخول مجهول
const signInAnonymouslyUser = async () => {
  const result = await signInAnonymously(auth.value);
  return result.user; // يرجع بيانات المستخدم
};

// تسجيل دخول بالبريد
const signInWithEmail = async (email: string, password: string) => {
  const result = await signInWithEmailAndPassword(auth.value, email, password);
  return result.user;
};

الخطوة 3: Firestore

// إضافة مستند
const addDocument = async (collectionName: string, data: DocumentData) => {
  // إضافة createdAt و updatedAt تلقائياً
  const docRef = await addDoc(collection(firestore.value, collectionName), {
    ...data,
    createdAt: new Date(),
    updatedAt: new Date()
  });
  return docRef; // يرجع مرجع المستند
};

// الاشتراك في مجموعة
const subscribeToCollection = (collectionName, callback, constraints) => {
  let q = query(collection(firestore.value, collectionName));

  // إضافة فلاتر
  if (constraints?.where) {
    constraints.where.forEach(([field, operator, value]) => {
      q = query(q, where(field, operator, value));
    });
  }

  // إرجاع دالة إلغاء الاشتراك
  return onSnapshot(q, callback);
};

الخطوة 4: Realtime Database

// إضافة بيانات جديدة
const pushRealtimeData = async (path: string, data: any) => {
  const dbRef = ref(database.value, path);
  const newRef = push(dbRef); // ينشئ مفتاح تلقائي
  await set(newRef, {
    ...data,
    timestamp: Date.now()
  });
  return newRef.key; // يرجع المفتاح التلقائي
};

// الاشتراك في التغييرات
const subscribeToRealtimeData = (path: string, callback: Function) => {
  const dbRef = ref(database.value, path);
  onValue(dbRef, (snapshot) => {
    callback(snapshot.val()); // استدعاء callback عند أي تغيير
  });

  return () => off(dbRef); // دالة إلغاء الاشتراك
};

مثال عملي كامل:

import { useFirebaseCore } from './useFirebaseCore';

const firebase = useFirebaseCore({
  config: firebaseConfig,
  onAuthStateChanged: (user) => {
    console.log('المستخدم:', user);
  }
});

// تهيئة Firebase
firebase.initializeFirebase();

// تسجيل دخول
await firebase.signInAnonymouslyUser();

// إضافة مستند
await firebase.addDocument('users', {
  name: 'أحمد',
  email: 'ahmed@example.com'
});

// الاشتراك في مجموعة
const unsubscribe = firebase.subscribeToCollection(
  'messages',
  (snapshot) => {
    snapshot.docs.forEach(doc => {
      console.log('رسالة جديدة:', doc.data());
    });
  },
  {
    where: [['read', '==', false]],
    orderBy: [['createdAt', 'desc']],
    limit: 10
  }
);

// إلغاء الاشتراك لاحقاً
unsubscribe();

3. `useFirebaseChat.ts` - شرح مفصل

الغرض من الملف:

يوفر نظام محادثات كامل مع دعم الغرف والرسائل الفورية والملفات.

كيف يعمل:

1. إنشاء غرفة محادثة:

const createRoom = async (participants: string[], name?: string) => {
  const roomData = {
    participants,  // مصفوفة معرفات المستخدمين
    name,          // اسم الغرفة (اختياري)
    createdAt: new Date(),
    updatedAt: new Date()
  };

  // حفظ في Firestore أو Realtime Database
  if (useRealtime) {
    const roomId = await pushRealtimeData('chats/rooms', roomData);
  } else {
    const docRef = await addDocument('chats/rooms', roomData);
    const roomId = docRef.id;
  }

  return roomId;
};

2. إرسال رسالة:

const sendMessage = async (roomId: string, body: string) => {
  const messageData = {
    body: body.trim(),
    type: 'text',
    senderId: currentUserId,
    senderName: currentUser.value?.displayName || 'Unknown',
    roomId,
    createdAt: new Date(),
    updatedAt: new Date()
  };

  // حفظ الرسالة
  if (useRealtime) {
    await pushRealtimeData(`chats/rooms/${roomId}/messages`, messageData);
  } else {
    await addDocument(`chats/rooms/${roomId}/messages`, messageData);
  }

  // تحديث آخر رسالة في الغرفة
  await updateDocument('chats/rooms', roomId, {
    lastMessage: messageData,
    lastMessageAt: new Date()
  });
};

3. Optimistic Updates (الرسائل المؤقتة):

const sendMessageOptimistic = async (roomId: string, body: string) => {
  // 1. إنشاء رسالة مؤقتة
  const tempMessage = {
    id: `temp-${Date.now()}`,
    body,
    isTemp: true,
    // ... باقي البيانات
  };

  // 2. إضافة الرسالة المؤقتة فوراً (قبل الإرسال)
  messages.value.push(tempMessage);

  try {
    // 3. إرسال الرسالة الحقيقية
    const messageId = await sendMessage(roomId, body);

    // 4. حذف الرسالة المؤقتة (الرسالة الحقيقية ستصل عبر الاشتراك)
    const tempIndex = messages.value.findIndex(msg => msg.id === tempMessage.id);
    messages.value.splice(tempIndex, 1);

    return messageId;
  } catch (error) {
    // 5. في حالة الفشل، حذف الرسالة المؤقتة
    const tempIndex = messages.value.findIndex(msg => msg.id === tempMessage.id);
    messages.value.splice(tempIndex, 1);
    throw error;
  }
};

4. الاشتراك في رسائل الغرفة:

const subscribeToRoom = async (roomId: string) => {
  currentRoomId.value = roomId;

  if (useRealtime) {
    // Realtime Database
    const unsubscribe = subscribeToRealtimeData(
      `chats/rooms/${roomId}/messages`,
      (data) => {
        // تحويل البيانات من كائن إلى مصفوفة
        const messagesArray = Object.entries(data).map(([id, messageData]) => ({
          id,
          ...messageData,
          createdAt: new Date(messageData.createdAt),
          updatedAt: new Date(messageData.updatedAt)
        }));

        // ترتيب حسب الوقت
        messagesArray.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());

        // تحديث الحالة
        messages.value = messagesArray;
      }
    );

    unsubscribeFunctions.value.push(unsubscribe);
  } else {
    // Firestore
    const unsubscribe = subscribeToCollection(
      `chats/rooms/${roomId}/messages`,
      (snapshot) => {
        const messagesArray = snapshot.docs.map(doc => ({
          id: doc.id,
          ...doc.data(),
          createdAt: doc.data().createdAt?.toDate() || new Date()
        }));

        messages.value = messagesArray;
      },
      {
        orderBy: [['createdAt', 'asc']] // ترتيب تصاعدي
      }
    );

    unsubscribeFunctions.value.push(unsubscribe);
  }
};

مثال عملي كامل:

import { useFirebaseChat } from './useFirebaseChat';

const chat = useFirebaseChat({
  config: firebaseConfig,
  useRealtime: false, // استخدام Firestore
  collectionName: 'chats',
  onNewMessage: (message) => {
    console.log('رسالة جديدة:', message);
    // تشغيل صوت
    playNotificationSound();
  }
});

// تهيئة
chat.initializeFirebase();
await chat.signInAnonymouslyUser();

// إنشاء غرفة
const roomId = await chat.createRoom(
  ['user1', 'user2'],
  'غرفة المحادثة'
);

// الاشتراك في الغرفة
await chat.subscribeToRoom(roomId);

// إرسال رسالة مع Optimistic Update
await chat.sendMessageOptimistic(roomId, 'مرحباً!');

// إرسال ملف
await chat.sendMessageOptimistic(
  roomId,
  'ملف مرفق',
  'attachment',
  [{
    fileName: 'document.pdf',
    type: 'application/pdf',
    url: 'https://example.com/file.pdf',
    size: 1024000
  }]
);

4. `useFirebaseNotifications.ts` - شرح مفصل

الغرض من الملف:

يوفر نظام إشعارات كامل مع دعم Push Notifications وعداد الإشعارات غير المقروءة.

كيف يعمل:

1. إنشاء إشعار:

const createNotification = async (
  title: string,
  message: string,
  type: 'info' | 'success' | 'warning' | 'error' = 'info',
  userId?: string
) => {
  const notificationData = {
    title,
    message,
    type,
    userId: userId || getCurrentUserId(), // إذا لم يُحدد، يستخدم المستخدم الحالي
    read: false,
    createdAt: new Date(),
    updatedAt: new Date()
  };

  if (useRealtime) {
    const notificationId = await pushRealtimeData('notifications', notificationData);
  } else {
    const docRef = await addDocument('notifications', notificationData);
    const notificationId = docRef.id;
  }

  return notificationId;
};

2. تمييز إشعار كمقروء:

const markAsRead = async (notificationId: string) => {
  // تحديث في قاعدة البيانات
  if (useRealtime) {
    await updateRealtimeData(`notifications/${notificationId}`, {
      read: true,
      updatedAt: new Date()
    });
  } else {
    await updateDocument('notifications', notificationId, {
      read: true,
      updatedAt: new Date()
    });
  }

  // تحديث الحالة المحلية
  const notification = notifications.value.find(n => n.id === notificationId);
  if (notification && !notification.read) {
    notification.read = true;
    unreadCount.value = Math.max(0, unreadCount.value - 1);
  }
};

3. الاشتراك في إشعارات المستخدم:

const subscribeToUserNotifications = async () => {
  const currentUserId = getCurrentUserId();

  if (useRealtime) {
    const unsubscribe = subscribeToRealtimeData(
      'notifications',
      (data) => {
        // تصفية الإشعارات الخاصة بالمستخدم فقط
        const notificationsArray = Object.entries(data)
          .filter(([_, notificationData]) => 
            notificationData.userId === currentUserId
          )
          .map(([id, notificationData]) => ({
            id,
            ...notificationData,
            createdAt: new Date(notificationData.createdAt)
          }));

        // ترتيب حسب التاريخ (الأحدث أولاً)
        notificationsArray.sort((a, b) => 
          b.createdAt.getTime() - a.createdAt.getTime()
        );

        notifications.value = notificationsArray;
        updateUnreadCount(); // تحديث العداد
      }
    );

    unsubscribeFunctions.value.push(unsubscribe);
  } else {
    // Firestore مع فلتر
    const unsubscribe = subscribeToCollection(
      'notifications',
      (snapshot) => {
        const notificationsArray = snapshot.docs
          .filter(doc => doc.data().userId === currentUserId)
          .map(doc => ({
            id: doc.id,
            ...doc.data(),
            createdAt: doc.data().createdAt?.toDate() || new Date()
          }));

        notifications.value = notificationsArray;
        updateUnreadCount();
      },
      {
        where: [['userId', '==', currentUserId]],
        orderBy: [['createdAt', 'desc']]
      }
    );

    unsubscribeFunctions.value.push(unsubscribe);
  }
};

4. تحديث عداد الإشعارات غير المقروءة:

const updateUnreadCount = () => {
  // حساب عدد الإشعارات غير المقروءة
  unreadCount.value = notifications.value.filter(n => !n.read).length;
};

5. Push Notifications:

const initializePushNotifications = async () => {
  // 1. طلب إذن الإشعارات
  const permission = await Notification.requestPermission();

  if (permission === 'granted') {
    // 2. الحصول على token
    const token = await getToken(messaging.value, {
      vapidKey: options.messagingConfig?.vapidKey
    });

    console.log('Push token:', token);
    // 3. إرسال token للسيرفر لحفظه
    return token;
  } else {
    throw new Error('Notification permission denied');
  }
};

// الاشتراك في استقبال الرسائل
const subscribeToPushMessages = (callback: Function) => {
  return onMessage(messaging.value, (payload) => {
    // استدعاء callback عند استلام رسالة push
    callback(payload);

    // يمكن إضافة الإشعار إلى القائمة المحلية
    addNotification({
      id: payload.messageId || Date.now().toString(),
      title: payload.notification?.title || 'إشعار جديد',
      message: payload.notification?.body || '',
      type: 'info',
      read: false,
      createdAt: new Date(),
      updatedAt: new Date()
    });
  });
};

مثال عملي كامل:

import { useFirebaseNotifications } from './useFirebaseNotifications';

const notifications = useFirebaseNotifications({
  config: firebaseConfig,
  useRealtime: false,
  collectionName: 'notifications',
  onNewNotification: (notification) => {
    console.log('إشعار جديد:', notification);
    // إظهار toast notification
    showToast(notification.title, notification.message);
  }
});

// تهيئة
notifications.initializeFirebase();
await notifications.signInAnonymouslyUser();

// الاشتراك في الإشعارات
await notifications.subscribeToUserNotifications();

// تهيئة Push Notifications
const token = await notifications.initializePushNotifications();
// إرسال token للسيرفر
await saveTokenToServer(token);

// الاشتراك في Push Messages
notifications.subscribeToPushMessages((payload) => {
  console.log('رسالة push:', payload);
});

// إنشاء إشعار
await notifications.createNotification(
  'مرحباً',
  'هذا إشعار تجريبي',
  'info'
);

// تمييز كمقروء
await notifications.markAsRead(notificationId);

// الحصول على الإشعارات غير المقروءة
const unread = notifications.getUnreadNotifications();
console.log('غير مقروء:', unread.length);

5. `useFirebaseExample.ts` - شرح مفصل

الغرض من الملف:

يوفر مثال كامل يوضح كيفية استخدام جميع Composables معاً في مشروع حقيقي. يعمل كـ wrapper يجمع جميع الوظائف في مكان واحد.

كيف يعمل:

1. تهيئة Composables:

export const useFirebaseExample = () => {
  // تكوين Firebase
  const firebaseConfig: FirebaseConfig = {
    apiKey: 'YOUR_FIREBASE_API_KEY',
    // ... باقي التكوين
  };

  // تهيئة Chat Composable
  const chatFirebase = useFirebaseChat({
    config: firebaseConfig,
    useRealtime: false,
    collectionName: 'chats',
    onNewMessage: (message) => {
      console.log('رسالة جديدة:', message);
    }
  });

  // تهيئة Notifications Composable
  const notificationFirebase = useFirebaseNotifications({
    config: firebaseConfig,
    useRealtime: false,
    collectionName: 'notifications',
    onNewNotification: (notification) => {
      console.log('إشعار جديد:', notification);
    }
  });

  // ... باقي الكود
};

2. وظائف مساعدة للمحادثات:

const initializeChat = async () => {
  // 1. تهيئة Firebase
  chatFirebase.initializeFirebase();

  // 2. انتظار قليل للاتصال
  await new Promise(resolve => setTimeout(resolve, 1000));

  // 3. الاشتراك في غرف المستخدم
  await chatFirebase.subscribeToUserRooms();

  console.log('تم تهيئة المحادثات بنجاح');
};

const sendChatMessage = async (roomId: string, messageText: string) => {
  // استخدام sendMessageOptimistic للسرعة
  const messageId = await chatFirebase.sendMessageOptimistic(
    roomId,
    messageText
  );
  return messageId;
};

3. وظائف مساعدة للإشعارات:

const initializeNotifications = async () => {
  // 1. تهيئة Firebase
  notificationFirebase.initializeFirebase();

  // 2. انتظار قليل
  await new Promise(resolve => setTimeout(resolve, 1000));

  // 3. الاشتراك في إشعارات المستخدم
  await notificationFirebase.subscribeToUserNotifications();

  // 4. تهيئة Push Notifications
  await notificationFirebase.initializePushNotifications();

  console.log('تم تهيئة الإشعارات بنجاح');
};

4. إرجاع جميع القيم والوظائف:

return {
  // حالة المحادثات
  chatMessages: chatFirebase.messages,
  chatRooms: chatFirebase.rooms,
  chatConnected: chatFirebase.isAuthenticated,

  // حالة الإشعارات
  notifications: notificationFirebase.notifications,
  unreadCount: notificationFirebase.unreadCount,

  // حالة المستخدم
  currentUser: chatFirebase.currentUser,

  // وظائف المحادثات
  initializeChat,
  joinChatRoom,
  sendChatMessage,

  // وظائف الإشعارات
  initializeNotifications,
  createNotification,
  markNotificationAsRead,

  // وظائف المصادقة
  signInAnonymously,
  signInWithEmail,
  signOut,

  // وظائف التنظيف
  cleanupAll
};

مثال عملي كامل في Vue Component:

<template>
  <div>
    <!-- حالة الاتصال -->
    <div v-if="chatLoading">جاري التحميل...</div>
    <div v-else-if="chatConnected">متصل ✅</div>
    <div v-else>غير متصل ❌</div>

    <!-- غرف المحادثة -->
    <div class="rooms">
      <div 
        v-for="room in chatRooms" 
        :key="room.id"
        @click="joinRoom(room.id)"
        :class="{ active: chatCurrentRoom === room.id }"
      >
        {{ room.name || `غرفة ${room.id}` }}
        <span v-if="room.lastMessage">
          {{ room.lastMessage.body }}
        </span>
      </div>
    </div>

    <!-- الرسائل -->
    <div class="messages">
      <div 
        v-for="message in chatMessages" 
        :key="message.id"
        :class="{ temp: message.isTemp }"
      >
        <strong>{{ message.senderName }}:</strong>
        {{ message.body }}
        <span v-if="message.isTemp" class="sending">جاري الإرسال...</span>
      </div>
    </div>

    <!-- إرسال رسالة -->
    <div class="send-message">
      <input 
        v-model="newMessage" 
        @keyup.enter="sendMessage"
        placeholder="اكتب رسالة..."
      />
      <button @click="sendMessage">إرسال</button>
    </div>

    <!-- الإشعارات -->
    <div class="notifications">
      <div class="header">
        <h3>الإشعارات</h3>
        <span class="badge">{{ unreadCount }}</span>
        <button @click="markAllAsRead">تمييز الكل كمقروء</button>
      </div>

      <div 
        v-for="notification in notifications" 
        :key="notification.id"
        :class="{ unread: !notification.read }"
      >
        <h4>{{ notification.title }}</h4>
        <p>{{ notification.message }}</p>
        <button 
          v-if="!notification.read"
          @click="markAsRead(notification.id)"
        >
          تمييز كمقروء
        </button>
      </div>
    </div>
  </div>
</template>

<script setup>
import { useFirebaseExample } from '@/composables/useFirebaseExample';

const {
  // الحالة
  chatMessages,
  chatRooms,
  chatCurrentRoom,
  chatConnected,
  chatLoading,
  notifications,
  unreadCount,
  currentUser,

  // الوظائف
  initializeChat,
  joinChatRoom,
  sendChatMessage,
  initializeNotifications,
  createNotification,
  markNotificationAsRead,
  markAllNotificationsAsRead,
  signInAnonymously,
  cleanupAll
} = useFirebaseExample();

const newMessage = ref('');
const selectedRoomId = ref('');

// تهيئة عند تحميل المكون
onMounted(async () => {
  try {
    // 1. تسجيل الدخول
    await signInAnonymously();

    // 2. تهيئة المحادثات والإشعارات معاً
    await Promise.all([
      initializeChat(),
      initializeNotifications()
    ]);

    console.log('تم التهيئة بنجاح');
  } catch (error) {
    console.error('خطأ في التهيئة:', error);
  }
});

// الانضمام لغرفة
const joinRoom = async (roomId: string) => {
  selectedRoomId.value = roomId;
  await joinChatRoom(roomId);
};

// إرسال رسالة
const sendMessage = async () => {
  if (!newMessage.value.trim() || !selectedRoomId.value) return;

  try {
    await sendChatMessage(selectedRoomId.value, newMessage.value);
    newMessage.value = ''; // مسح الحقل
  } catch (error) {
    console.error('خطأ في إرسال الرسالة:', error);
  }
};

// تمييز إشعار كمقروء
const markAsRead = async (notificationId: string) => {
  await markNotificationAsRead(notificationId);
};

// تمييز الكل كمقروء
const markAllAsRead = async () => {
  await markAllNotificationsAsRead();
};

// تنظيف عند إغلاق المكون
onUnmounted(() => {
  cleanupAll();
});
</script>

🚀 كيفية الاستخدام

الخطوة 1: تثبيت Firebase

npm install firebase

الخطوة 2: نسخ الملفات

انسخ جميع الملفات من مجلد composables إلى مشروعك.

الخطوة 3: تعديل التكوين

في ملف useFirebaseExample.ts أو في ملف التكوين الخاص بك:

const firebaseConfig: FirebaseConfig = {
  apiKey: 'YOUR_FIREBASE_API_KEY',
  authDomain: 'your-project.firebaseapp.com',
  projectId: 'your-project-id',
  storageBucket: 'your-project.appspot.com',
  messagingSenderId: '123456789',
  appId: '1:123456789:web:abcdef123456',
  measurementId: 'G-XXXXXXXXXX'
};

الخطوة 4: الاستخدام في المكون

<template>
  <div>
    <!-- حالة الاتصال -->
    <div class="connection-status">
      <span :class="chatConnected ? 'connected' : 'disconnected'">
        {{ chatConnected ? 'متصل' : 'غير متصل' }}
      </span>
    </div>

    <!-- غرف المحادثة -->
    <div class="chat-rooms">
      <div v-for="room in chatRooms" :key="room.id" class="room" @click="joinRoom(room.id)">
        {{ room.name || `غرفة ${room.id}` }}
      </div>
    </div>

    <!-- الرسائل -->
    <div class="messages">
      <div v-for="message in chatMessages" :key="message.id" class="message">
        <strong>{{ message.senderName }}:</strong> {{ message.body }}
      </div>
    </div>

    <!-- إرسال رسالة -->
    <div class="send-message">
      <input v-model="newMessage" placeholder="اكتب رسالة..." />
      <button @click="sendMessage">إرسال</button>
    </div>

    <!-- الإشعارات -->
    <div class="notifications">
      <div v-for="notification in notifications" :key="notification.id" class="notification">
        <h4>{{ notification.title }}</h4>
        <p>{{ notification.message }}</p>
        <button @click="markAsRead(notification.id)">تمييز كمقروء</button>
      </div>
      <span class="unread-count">{{ unreadCount }}</span>
    </div>
  </div>
</template>

<script setup>
import { useFirebaseExample } from '@/composables/useFirebaseExample';

const {
  chatMessages,
  chatRooms,
  notifications,
  unreadCount,
  currentUser,
  chatConnected,
  initializeChat,
  joinChatRoom,
  sendChatMessage,
  initializeNotifications,
  createNotification,
  markNotificationAsRead,
  signInAnonymously,
  cleanupAll
} = useFirebaseExample();

const newMessage = ref('');
const selectedRoomId = ref('');

// تهيئة Firebase
onMounted(async () => {
  // تسجيل الدخول كضيف
  await signInAnonymously();

  // تهيئة المحادثات والإشعارات
  await Promise.all([
    initializeChat(),
    initializeNotifications()
  ]);
});

// الانضمام لغرفة محادثة
const joinRoom = async (roomId: string) => {
  selectedRoomId.value = roomId;
  await joinChatRoom(roomId);
};

// إرسال رسالة
const sendMessage = async () => {
  if (!newMessage.value.trim() || !selectedRoomId.value) return;

  try {
    await sendChatMessage(selectedRoomId.value, newMessage.value);
    newMessage.value = ''; // مسح الرسالة
  } catch (error) {
    console.error('خطأ في إرسال الرسالة:', error);
  }
};

// تمييز إشعار كمقروء
const markAsRead = async (notificationId: string) => {
  try {
    await markNotificationAsRead(notificationId);
  } catch (error) {
    console.error('خطأ في تمييز الإشعار كمقروء:', error);
  }
};

// تنظيف عند إغلاق المكون
onUnmounted(() => {
  cleanupAll();
});
</script>

🔧 التخصيص

اختيار نوع قاعدة البيانات

const chatFirebase = useFirebaseChat({
  config: firebaseConfig,
  useRealtime: false, // true للـ Realtime Database، false للـ Firestore
  collectionName: 'chats', // يمكن تغييرها
  // ...
});

تغيير أسماء المجموعات

const notificationFirebase = useFirebaseNotifications({
  config: firebaseConfig,
  collectionName: 'notifications', // يمكن تغييرها
  // ...
});

إضافة معالجات الأحداث

const chatFirebase = useFirebaseChat({
  config: firebaseConfig,
  onNewMessage: (message) => {
    // منطق مخصص عند استلام رسالة جديدة
    console.log('رسالة جديدة:', message);
    // يمكن إضافة صوت أو إشعار هنا
  },
  onMessageError: (error) => {
    // منطق مخصص عند حدوث خطأ
    console.error('خطأ في الرسالة:', error);
  },
  // ...
});

📋 الميزات

المحادثات

✅ رسائل فورية
✅ رسائل مؤقتة (Optimistic Updates)
✅ إرسال ملفات
✅ إدارة الغرف
✅ إدارة الأخطاء
✅ تنظيف الموارد
✅ دعم Firestore و Realtime Database

الإشعارات

✅ إشعارات فورية
✅ عداد الإشعارات غير المقروءة
✅ تمييز الإشعارات كمقروءة
✅ تصفية الإشعارات حسب النوع
✅ إدارة الإشعارات
✅ Push Notifications
✅ دعم Firestore و Realtime Database

المصادقة

✅ تسجيل دخول مجهول
✅ تسجيل دخول بالبريد الإلكتروني
✅ إدارة حالة المستخدم
✅ تسجيل الخروج

عام

✅ إدارة الاتصال
✅ معالجة الأخطاء
✅ تنظيف الذاكرة
✅ قابلية التخصيص
✅ TypeScript support
✅ دعم جميع خدمات Firebase

📝 ملاحظات

تأكد من إعداد مشروع Firebase في Firebase Console
تأكد من تفعيل الخدمات المطلوبة (Authentication, Firestore/Realtime Database, Messaging)
استخدم قواعد الأمان المناسبة في Firestore/Realtime Database
قم بتنظيف الموارد عند إغلاق المكونات

🔥 خدمات Firebase المدعومة

Authentication

تسجيل دخول مجهول
تسجيل دخول بالبريد الإلكتروني
إدارة حالة المستخدم

Firestore

إضافة/تحديث/حذف المستندات
الاشتراك في التغييرات
الاستعلامات مع الفلاتر والترتيب

Realtime Database

إضافة/تحديث/حذف البيانات
الاشتراك في التغييرات
إدارة المسارات

Cloud Messaging

Push Notifications
إدارة الأذونات
استقبال الرسائل

Download Firebase Composables

Nuxt 4.2 — A Deep, Comprehensive Guide to Everything New

Ahmed Niazy — Tue, 18 Nov 2025 10:03:34 +0000

Nuxt 4.2 is one of those releases that quietly delivers huge improvements across the DX (developer experience), performance, debugging, and TypeScript productivity spectrum.
It doesn’t introduce flashy breaking changes or conceptual complexity — instead, it refines the core parts of Nuxt that developers rely on every day.

This article is a complete, long-form deep dive.
By the end, you’ll fully understand every update in Nuxt 4.2, why it exists, and how to apply it with real examples and practical scenarios.

Let’s dig in.

Nuxt 4.2 Introduces Abortable `useAsyncData` — A Must-Have for Real Apps

For years, developers asked for a way to cancel running data-fetch operations when the user triggers a new action or navigates before the request completes.

Nuxt 4.2 finally brings full support for AbortController inside useAsyncData().

Why This Matters

Imagine a search box where the user types fast, triggering multiple data loads.
Without cancellation:

You waste network requests
You risk showing outdated results
You create race conditions

Now, you can abort the previous request before starting a new one.

How It Works

const controller = new AbortController()

const { data, pending, error, refresh } = useAsyncData(
  'search',
  () => $fetch('/api/search?q=' + query.value, {
    signal: controller.signal
  })
)

// abort previous request when new input happens
watch(query, () => {
  controller.abort()
  refresh()
})

What Happens Internally?

When the request is aborted, Nuxt catches the abort error.
The pending state is cleared immediately.
useAsyncData does not update data.
No race conditions occur.

When to Use This

Live search
Infinite scroll
Auto-refresh dashboards
Form steps that change rapidly

It is not only a DX improvement — it prevents bugs that actually happen in real production apps.

New: Better Error Pages in Development (A Perfect Blend of Your UI + Debug Info)

This is one of the most underrated updates in all of Nuxt 4.x.

Previously, if your app crashed during development, Nuxt showed a generic error overlay.
If you created a custom error page (error.vue), you couldn’t preview how it actually looked during runtime errors.

Nuxt 4.2 changes this completely.

You Now Get TWO Things at the Same Time:

Your actual Nuxt error page (the one your users see in production)
The Vite error overlay with stack trace and debugging tools

Both appear simultaneously, layered intelligently.

Example Error Page (`error.vue`)

<script setup>
defineProps({ error: Object })
</script>

<template>
  <div class="error-page">
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <NuxtLink to="/">Go Home</NuxtLink>
  </div>
</template>

Now in development:

You see the real design plus full debugging tools.
You don’t need to choose one or hack the system anymore.

Benefits

You can design UX for failures with full confidence.
You debug faster.
You no longer switch between two different error “worlds.”

Vite Environment API — A Cleaner, More Predictable Env System

Nuxt already offers runtimeConfig, which is great for secure environment variables.

But developers still want to use the familiar:

import.meta.env

Nuxt 4.2 now supports it experimentally via:

export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true
  }
})

Why This Matters

If you work with:

Third-party tools
UI libraries
Shared code across multiple projects

You often need import.meta.env to work exactly like Vite.

Now it does.

Example

const apiUrl = import.meta.env.VITE_API_URL

When to Prefer This

When migrating Vite apps into Nuxt
When you need identical behavior between SPA and SSR environments
When integrating libraries relying heavily on import.meta.env

Huge Performance Wins: Async Data Handler Extraction

This is a big one.
Enabled via:

export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true
  }
})

What It Actually Does

useAsyncData() often contains server-only logic like:

useAsyncData(() => {
  return $fetch('/api/products')
})

This logic should not be inside the client bundle.
But historically, it ended up there because Nuxt had to include it for hydration purposes.

Nuxt 4.2 extracts this server-only logic so the browser never downloads it.

Real Impact

Depending on how many useAsyncData() calls your project has:

Bundle size drops 20%–40%
Faster hydration
Faster first load
Less JavaScript sent to the client

This is a rare “enable and enjoy free performance” update.

TypeScript Plugin Support — This Is Next-Level DX

This new feature is experimental and extremely powerful for large Nuxt codebases.

Enable it:

export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true
  }
})

What You Get

1. Component Auto-Rename

Rename a Vue file and all references update automatically.

2. Go To Definition for Runtime Utilities

Jump into:

useState()
useFetch()
Nuxt composables
Config generated types

3. Better IntelliSense Across the Entire Project

Nuxt becomes easier to navigate, especially in mid–large codebases.

Example Scenario

You rename:

components/BaseButton.vue → components/Button.vue

Nuxt TypeScript plugin updates:

<BaseButton/>

into:

<Button/>

magically, everywhere.

This is something developers have wanted for years.

Smaller Quality-of-Life Improvements

#1: `routeRules` Now Keep the Hash

Before:

/products#top → /products

After:

No hash loss.

#2: `<NuxtLink>` Supports Object Href

<NuxtLink :href="{ name: 'product', params: { id: 12 } }">
  View Product
</NuxtLink>

#3: Auto-Imported Components Work with `h()`

import { h } from 'vue'

export default defineComponent({
  render() {
    return h(MyCard, { title: 'Hello' })
  }
})

No need for manual imports anymore.

How to Upgrade to Nuxt 4.2

Just run:

npx nuxt upgrade --dedupe

Nuxt automatically updates dependencies and resolves duplicates.

Final Thoughts

Nuxt 4.2 isn’t a huge feature release — it’s a developer happiness release.

It gives you:

More control over async data
Better debugging
Faster loading
Cleaner environment handling
Significantly improved TypeScript support
Smarter routing and linking behavior

And all of this without breaking anything.

If you're building modern Vue applications, Nuxt 4.2 is one of the cleanest, smoothest upgrades you’ll ever apply.

Deep Dive into State Management in Vue 3: From Composition API to Pinia with Practical Insights

Ahmed Niazy — Sun, 26 Oct 2025 06:55:51 +0000

When you build a Vue 3 app, you inevitably face this: how should I manage the state? Do I just use the built-in features like ref, reactive, and composables via the Vue Composition API — or do I bring in a dedicated library like Pinia? This article will dive deep, get intense, pull apart the pros and cons, show you real code, ask you tough questions + give answers, and leave you with tasks. We’ll cover why it matters, when you might choose one over the other, and how you actually implement each.

Why state management even matters, and why this decision is HUGE

If your app is tiny – maybe one or two components – maybe state is trivial. But once you start growing: dozens of components, nested trees, modules, asynchronous fetches, caching, derived state, multiple teams working… the “state management” piece becomes mission critical. Mess it up, and you’ll have bugs, spaghetti, unpredictable side-effects, data out of sync, re-render chaos, and maintenance nightmares.

With Vue 3, you have this amazing power: the Composition API. It gives you flexibility, less ceremony, and the feeling of “just write plain JS”. On the flip side, you have Pinia, designed to be the “official” store library for Vue, offering structure, patterns, tooling, and ready-made store features.

This decision – “do I just in-house build my store logic via composables or adopt Pinia?” – can shape how scalable your app is, how maintainable, how easy to onboard new developers, and how comfortable you’ll be when things go wrong. The stakes are high.

Using Composition API (no external store library) – what it looks like, its benefits & risks

What it looks like

With the Composition API approach, you lean on these built-in features:

ref(), reactive(), computed(), watch()
You write your own “store” modules as simple JS/TS modules or composables
You might use provide/inject to share state across component trees
You don’t add a dedicated store library (so fewer dependencies)
Example:

// src/composables/useUsers.ts
import { ref, onMounted } from 'vue’
import type { Ref } from 'vue’

interface User {
  id: number
  name: string
}

export function useUsers(): { users: Ref<User[]>; loadUsers: () => Promise<void> } {
  const users = ref<User[]>([])

  async function loadUsers(): Promise<void> {
    // pretend fetchUsers fetches User[]
    users.value = await fetchUsers()
  }

  onMounted(() => {
    void loadUsers()
  })

  return { users, loadUsers }
}

Then to distribute it:

// injection-keys.ts
import type { InjectionKey } from 'vue’
import type { UsersHelper } from './useUsers’

export const usersHelperKey: InjectionKey<UsersHelper> = Symbol('usersHelper')

// ParentComponent.vue
<script setup lang="ts">
import { provide } from 'vue’
import { useUsers } from '@/composables/useUsers’
import { usersHelperKey } from '@/composables/injection-keys’

const usersHelper = useUsers()
provide(usersHelperKey, usersHelper)
</script>
<template>
  <ChildComponent />
</template>

// ChildComponent.vue
<script setup lang="ts">
import { inject } from 'vue’
import { usersHelperKey } from '@/composables/injection-keys’

const usersHelper = inject(usersHelperKey)
</script>
<template>
  <ul>
    <li v-for="u in usersHelper?.users" :key="u.id">{{ u.name }}</li>
  </ul>
</template>

Which shows: you can build your own mini store using the Composition API + provide/inject.

Benefits

No extra library to learn/install/configure → fewer dependencies.
Very flexible: you tailor your “store” exactly how you want it.
Lightweight: if your state needs are modest, this is ideal.
Keeps parts of your app separated (you only share what you want).
Great for small to medium projects, proof-of-concepts, or apps with limited state complexity.

Risks / drawbacks

As your app grows, you’ll likely end up reinventing parts of what store libraries already solve: modules, namespacing, devtools support, persist, hot reload, debugging etc.
Sharing global state or cross-tree state gets more manual (provide/inject or exporting singletons) – potential for mis-wiring or accidental coupling.
Without clear structure, you can drift into chaos: many files, inconsistent patterns, multiple “useX” composables doing similar things but subtle differences.
Harder to enforce patterns (especially across teams) or to debug/travel history of state changes.
If you plan on many modules, many developers, large codebase – you’ll probably pay cost in maintainability.

Using Pinia – what it looks like, why it’s powerful, and when you’ll want it

What it looks like

Pinia gives you a structured store definition; it’s built for Vue 3, and integrates with devtools. Example:

// src/stores/counter.ts
import { defineStore } from 'pinia’

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0
  }),
  getters: {
    doubleCount(state) {
      return state.count * 2
    }
  },
  actions: {
    increment(amount = 1) {
      this.count += amount
    }
  }
})

Then in a component:

<script setup lang="ts">
import { storeToRefs } from 'pinia’
import { useCounterStore } from '@/stores/counter’

const counter = useCounterStore()
const { count, doubleCount } = storeToRefs(counter)

function handleClick() {
  counter.increment()
}
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ doubleCount }}</p>
    <button @click="handleClick">Increment</button>
  </div>
</template>

That’s it. The structure is obvious: you have state, getters, actions. Pinia gives you all the things you expect from a store library, but with minimal boilerplate.

Why it’s powerful

Global registration: you can access your store from anywhere in the app easily.
DevTools integration: you get time-travel, inspect state changes, debug flows more easily.
Orderly structure: modules (stores) are well defined; no implicit “magic” leaks.
TypeScript support is strong (Pinia was built with TS in mind) → fewer type headaches.
Scaling is easier: when you add more features, more modules, more devs, the store architecture is solid.
Community momentum: since many Vue 3 apps now adopt Pinia, you’ll find patterns, plugins, ecosystem support.

When you’ll want it

If you’re building a large or medium-sized app (many components, many modules, cross-domain state).
If multiple developers will touch the state layer (you want consistency, predictability).
If you care about debugging, state traceability, devtools, hot module replacement.
If your state management is a non-trivial part of your app (carts, user sessions, persistent state, multiple modules, real-time events etc.).
If you want fewer custom “home-rolled” solutions and prefer something you can rely on.

Comparison – side by side

Here’s a more extreme breakdown of how they differ, when one shines, when one struggles.

Feature / Concern	Composition API (no store library)	Pinia
Setup overhead	Very low – just use composables + built-in APIs	Low to medium – install Pinia, register plugin, then define stores
Learning curve	Familiar JS + Vue concepts; freedom to design your own	Slight overhead to learn Pinia APIs, but straightforward
Dependency	Zero external store library; minimal footprint	One additional library (Pinia) added to your stack
Structure / Architecture	Loose – you design modules, naming, boundaries yourself	Defined – you create stores with state/getters/actions; architecture is more consistent
Sharing global state	Manual sharing (export singletons or provide/inject)	Built-in global shared store support
Debugging / Dev tools	More manual – you may need to create custom hooks/logging	Rich dev tools, time-travel, plugins, clear store snapshots
TypeScript support	Good but you may need more manual type definition or boilerplate	Very good – Pinia supports TS out of the box nicely
Scaling to large apps	Requires discipline, good architecture; risk of fragmentation	Built for scaling; modules, stores, team collaboration easier
Flexibility / freedom	Maximum freedom – you decide everything	Slightly less freedom (you follow Pinia’s pattern) but still very flexible
Lightweight apps	Ideal for small apps where adding a library feels heavy	Works, but may feel like overkill for very tiny apps
Team / maintainability	Requires standards, conventions to avoid spaghetti	Out-of-the-box conventions assist maintainability

The verdict (with some extreme emphasis)

If you are working on a small application or you know for sure that your state needs are modest, you might choose just the Composition API. It’s lean, fast to set up, no extra dependencies, and you can keep things simple.

But if you are building something non-trivial, or expect growth, or expect more team members, or you want the comfort of structured state management, then Pinia is the much safer bet. The added structure, tooling, clarity will repay you hugely when things get complex.

In fact: if I were building a “real world” app today, I would probably start with Pinia unless I was absolutely sure the app will remain trivial. Because once you reach a certain size, switching later is more painful than starting with the right tool.

Real-world code examples + comparisons

Here are two scenarios:

Using Composition API only
Same scenario using Pinia

Example Scenario: Shopping Cart

Composition API version

// src/composables/useCart.ts
import { reactive, computed } from 'vue’

interface CartItem {
  id: number
  name: string
  quantity: number
  price: number
}

const state = reactive({
  items: [] as CartItem[]
})

export function useCart() {
  const items = computed(() => state.items)

  const totalQuantity = computed(() => state.items.reduce((sum, i) => sum + i.quantity, 0))
  const totalPrice = computed(() => state.items.reduce((sum, i) => sum + i.quantity * i.price, 0))

  function addItem(item: CartItem) {
    const existing = state.items.find(i => i.id === item.id)
    if (existing) {
      existing.quantity += item.quantity
    } else {
      state.items.push(item)
    }
  }

  function removeItem(id: number) {
    const index = state.items.findIndex(i => i.id === id)
    if (index !== -1) {
      state.items.splice(index, 1)
    }
  }

  return {
    items,
    totalQuantity,
    totalPrice,
    addItem,
    removeItem
  }
}

Then in your components you import useCart() and everything is reactive. You don’t need to install anything extra.

Pros: simple, direct.
Cons: if you add many modules (cart, user, products, orders), you’ll need to manage each module’s file, potentially manage injection or exports. Debugging becomes manual. You’ll need to enforce “who uses what state” and avoid cross-module entanglement.

Pinia version

// src/stores/cart.ts
import { defineStore } from 'pinia’

interface CartItem {
  id: number
  name: string
  quantity: number
  price: number
}

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: [] as CartItem[]
  }),
  getters: {
    totalQuantity: (state) => state.items.reduce((sum, i) => sum + i.quantity, 0),
    totalPrice: (state) => state.items.reduce((sum, i) => sum + i.quantity * i.price, 0)
  },
  actions: {
    addItem(item: CartItem) {
      const existing = this.items.find(i => i.id === item.id)
      if (existing) {
        existing.quantity += item.quantity
      } else {
        this.items.push(item)
      }
    },
    removeItem(id: number) {
      const index = this.items.findIndex(i => i.id === id)
      if (index !== -1) {
        this.items.splice(index, 1)
      }
    }
  }
})

And in component:

<script setup lang="ts">
import { storeToRefs } from 'pinia’
import { useCartStore } from '@/stores/cart’

const cart = useCartStore()
const { items, totalQuantity, totalPrice } = storeToRefs(cart)

function handleAdd() {
  cart.addItem({ id: 1, name: 'Widget', quantity: 2, price: 10 })
}
</script>

<template>
  <div>
    <p>Total Items: {{ totalQuantity }}</p>
    <p>Total Price: {{ totalPrice }}</p>
    <button @click="handleAdd">Add Item</button>
    <ul>
      <li v-for="i in items" :key="i.id">
        {{ i.name }} × {{ i.quantity }} — ${{ i.price * i.quantity }}
        <button @click="cart.removeItem(i.id)">Remove</button>
      </li>
    </ul>
  </div>
</template>

Pros: structured, debugging tools, predictable, scalable.
Cons: slightly more setup, you must adopt Pinia’s style/patterns (which is fine for most). For trivial apps maybe it’s overhead.

Questions & Answers section

Q1. Is it wrong to use the Composition API only for everything, never using Pinia?
A1. Not at all wrong – for small or medium apps, Composition API alone is fully valid. But you must be disciplined: define modules, separate concerns, ensure you don’t end up with one giant “state bag” that everything reaches into. If you foresee growth, you’ll likely pay later.

Q2. If I start with Composition API and later switch to Pinia, will it be hard?
A2. It depends on how you structured things. If you kept things modular (each composable handles its own concerns) and you avoided ad-hoc state access everywhere, you’ll find migrating easier. If you have many components drilling state manually, you’ll probably need to refactor larger parts of your app.

Q3. Does Pinia lock me in or reduce flexibility?
A3. Not really. Pinia is quite flexible. You still write actions, getters, state. You can still use composables inside your stores. The pattern is clear but you retain freedom. The benefit is you get structure rather than rigid restriction.

Q4. What about performance – is using Pinia slower?
A4. In most cases, no significant difference. Pinia is lightweight and optimized for Vue 3. Unless you have extremely tight performance constraints, the overhead is negligible compared to the developer benefit of structure and tooling.

Q5. What factors should influence my choice between the two?
A5. Factors to check:

How many modules / domains in your state (cart, user, products, etc.).
Do you have multiple developers working on state?
Do you need debugging tools / time-travel / devtools support?
Will the state grow more complex (async, derived, caching, resets)?
Is the application expected to scale significantly?
How comfortable are you with building your own structure vs using a built-in one?

Tasks for you to try

Here are some hands-on tasks to cement the knowledge. Try both approaches.

Task A (Composition API only):

Create a simple blog app: posts + comments.
Build a composable usePosts() that loads posts from a mock API, tracks loading/error state, allows adding a post.
Build useComments(postId) that loads comments for a given post, allows adding/removing comments.
Make sure you share state as needed between parent/child components (maybe via provide/inject) or a simple module export.
Then measure: how easy is it to access posts + comments from arbitrary components? How easy to debug? What happens when state gets more complex (e.g., caching, concurrent loads)?

Task B (Pinia version):

Convert the blog app using Pinia. Create two stores: postsStore and commentsStore.
In each store, keep state, getters (e.g., commentsCount), and actions (e.g., fetchPosts, addPost, fetchComments, addComment).
Use the stores in components. Use devtools to inspect state changes.
Reflect: How did the architecture differ? Which one felt cleaner? Which one easier to maintain when you add more features (e.g., editing posts, filtering posts, reacting to user login)?

Task C (Scaling scenario):

Pretend your blog app is going to expand: you’ll add user authentication, user preferences, theme switching, notifications, offline caching, and multiple teams contributing.
Map out (by hand or in a doc) how you would structure your state modules in each approach (Composition API only vs Pinia).
Identify potential pain points in each. For example: in the Composition API version you might have many small composables, some of them overlapping responsibilities; in the Pinia version you might need to decide on store names, module splitting, but you already have clear patterns.
Decide which approach you would adopt for this scaling scenario and write down your reasoning.

Final thoughts (and a bit of hyperbole)

Let’s be clear: Choosing between “Composition API alone” vs “Pinia” is not just a small internal decision. It can define how maintainable, scalable, and pleasant your development experience will be. If you ignore structure now, you may pay for it later in chaotic merges, obscure bugs, duplicated logic, and developer frustration.

On the other hand, if you skip over-engineering and keep it simple when it's simple, you’ll save time, keep things nimble, and avoid bloat. There’s a sweet spot.

But please: don’t assume one size fits all. It’s okay to start simple. It’s okay to evolve. What matters is that you choose intentionally, not by default.

If I were to issue a bold statement:

"If you think your app will even remotely grow beyond trivial size, pick Pinia. If you’re absolutely sure it will stay tiny, the Composition API alone will serve."

And yes — if you pick Composition API now and later hit scaling constraints, migrating may cost more than deciding right up front. But it’s also true that starting with Pinia in a 2-page app might feel like using a sledgehammer to crack a nut.

In the end: you want clarity, predictability, maintainability, and developer happiness. Choose the tool that supports that for your context. Write your composables or build your stores, and keep your state management not just working — but elegant.

DEV Community: Ahmed Niazy

Advanced TypeScript Type System — The Complete Deep Dive

📚 Table of Contents

1️⃣ Quick Type System Refresher (In 5 Minutes)

Structural Typing

2️⃣ How Type Narrowing Works Internally

Example: Discriminated Union

3️⃣ Conditional Types — The Core Engine

What Actually Happens?

4️⃣ Distributive Conditional Types — Hidden Power

Why?

Prevent Distribution

5️⃣ The infer Keyword — Type Pattern Matching

Extract Return Type

Extract First Argument

Deep Extraction Example

6️⃣ Mapped Types — Iteration at Type Level

7️⃣ Key Remapping & Property Filtering

Filtering Keys

8️⃣ Template Literal Types — Compile-Time String Engine

Cartesian Explosion

9️⃣ Recursive Types — Type-Level Recursion

🔟 Building Advanced Custom Utility Types

DeepPartial

Keys By Value Type

Flatten Nested Object (Caution: can be expensive)

1️⃣1️⃣ Reverse Engineering DefinitelyTyped

1️⃣2️⃣ Variance — The Hidden Foundation

Covariance Example

Contravariance (Function Parameters)

Bivariance (Historical Loophole)

1️⃣3️⃣ Union to Intersection — The “Variance Hack” Explained

What’s happening step-by-step?

Step 1: Distribute into functions

Step 2: Infer the parameter

1️⃣4️⃣ Higher-Order Types & Type-Level Function Composition

Apply — Calling a Type-Level Function

Defining a “type-level function”

Type-Level Composition (“Piping”)

1️⃣5️⃣ Advanced infer Tricks (Tuples, Promises, and More)

Head / Tail of a Tuple

Reverse a Tuple (Recursive)

Extract Promise Inner Type

1️⃣6️⃣ Type-Level Parsing (String Manipulation)

Extract Route Params

1️⃣7️⃣ Building a Fully Type-Safe Event System

1️⃣8️⃣ Exhaustiveness Checking with never

1️⃣9️⃣ Compiler Limits — What Actually Breaks

Extremely Dangerous Pattern (Union Explosion)

2️⃣0️⃣ Performance Impact of Complex Types

Common Errors

What Causes Slowness?

2️⃣1️⃣ Practical Guidelines for Production Systems

✅ Prefer Shallow Utilities

✅ Avoid Naked Distribution When Not Needed

✅ Break Complex Types Into Steps

✅ Profile Large Codebases

🧠 Final Thoughts

A Deep Dive Into Schema.org Structured Data For SEO

Important note

What this file contains

How to use outputs in SEO

Structured data can help with

Shared dependencies inside the schema module

The helper methods focus on

Organization schema

Generator

Goal

Input interface

Output shape

Address field

ContactPoint field

sameAs field

SEO value of Organization schema

WebPage schema

Generator

Goal

Input interface

Output shape

isPartOf field

5️⃣ The `infer` Keyword — Type Pattern Matching

`Apply` — Calling a Type-Level Function

1️⃣5️⃣ Advanced `infer` Tricks (Tuples, Promises, and More)

1️⃣8️⃣ Exhaustiveness Checking with `never`