ECS Experiment

.cursor/rules/style-guide.mdc

@@ -0,0 +1,319 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Style Guide
+
+Core coding standards and style guidelines for our TypeScript codebase. These guidelines ensure consistency, maintainability, and high code quality across the project.
+
+## Core Principles
+- **KISS (Keep It Simple, Stupid)** - Always choose the simplest, most maintainable solution
+- **TypeScript First** - Always use TypeScript with strict typing (`strict: true`) everywhere
+- **Less is More** - Always avoid unnecessary complexity, the best code is no code
+- **Self-Documenting** - Always make code obvious and clear without comments
+
+## File Organization
+
+### Directory Structure
+- Always organize code in a predictable and scalable way
+- Always keep related code close together
+- Always use clear, descriptive directory names
+- Always follow consistent patterns across the project
+- Always use singular for categories/domains (e.g., `auth/`, `user/`, `product/`)
+- Always use plural for collections/lists (e.g., `components/`, `hooks/`, `utils/`)
+
+✅ Good:
+```typescript
+src/
+  auth/              # Singular: domain
+    components/      # Plural: collection
+    hooks/          # Plural: collection
+    lib/            # Singular: category
+
+  user/             # Singular: domain
+    components/     # Plural: collection
+    hooks/         # Plural: collection
+    lib/           # Singular: category
+
+  lib/             # Singular: core category
+  components/      # Plural: shared collection
+  hooks/          # Plural: shared collection
+```
+
+❌ Bad:
+```typescript
+src/
+  auths/           # Wrong: Category should be singular
+    component/     # Wrong: Collection should be plural
+
+  users/          # Wrong: Category should be singular
+    hook/         # Wrong: Collection should be plural
+
+  libraries/      # Wrong: Category should be singular
+  shared-components/ # Wrong: Use simple plural
+```
+
+### Files & Directories
+- Always use consistent and predictable naming patterns
+- Always make names descriptive and purpose-indicating
+- Always follow established community conventions
+
+✅ Good:
+```typescript
+// Directories (kebab-case)
+src/
+  auth/
+    components/
+    hooks/
+    lib/
+
+// Regular Files (kebab-case)
+user-service.ts
+jwt-utils.ts
+date-formatter.ts
+api-client.ts
+
+// Component Files (PascalCase)
+UserProfileCard.tsx
+OrderSummaryTable.tsx
+PaymentMethodSelector.tsx
+ButtonPrimary.tsx
+
+// Class Files (PascalCase)
+OrderProcessor.ts
+PaymentGateway.ts
+CacheManager.ts
+```
+
+❌ Bad:
+```typescript
+// Directories (mixed case)
+src/
+  UserManagement/     # Wrong: PascalCase directory
+  order_processing/   # Wrong: snake_case directory
+  PAYMENT/           # Wrong: UPPERCASE directory
+  Shared-Utils/      # Wrong: Mixed kebab-case and PascalCase
+
+// Files (inconsistent)
+userService.ts      # Wrong: camelCase
+USER_HELPERS.ts    # Wrong: SNAKE_CASE
+payment.utilities.ts # Wrong: dot notation
+Api.Client.ts      # Wrong: PascalCase with dots
+```
+
+### Code Identifiers
+- Always use clear, descriptive names that indicate purpose
+- Always follow TypeScript community standards
+- Always maintain consistent prefixing for special types
+
+✅ Good:
+```typescript
+// Variables & Functions (camelCase)
+const currentUser = getCurrentUser();
+const isValidEmail = validateEmail(email);
+const calculateTotalPrice = (items: TOrderItem[]): number => {
+  return items.reduce((sum, item) => sum + item.price, 0);
+};
+
+// Interfaces & Types (T prefix)
+type TUser = {
+  id: string;
+  email: string;
+  profile: TUserProfile;
+};
+
+type TOrderItem = {
+  id: string;
+  productId: string;
+  quantity: number;
+  price: number;
+};
+
+// Enums (E prefix)
+enum EOrderStatus {
+  Pending = 'pending',
+  Processing = 'processing',
+  Completed = 'completed',
+  Cancelled = 'cancelled'
+}
+
+enum EUserRole {
+  Admin = 'admin',
+  Customer = 'customer',
+  Guest = 'guest'
+}
+
+// Schemas (S prefix)
+const SUserProfile = z.object({
+  firstName: z.string().min(2),
+  lastName: z.string().min(2),
+  dateOfBirth: z.date().optional(),
+  phoneNumber: z.string().regex(/^\+?[1-9]\d{1,14}$/).optional()
+});
+
+const SOrderCreate = z.object({
+  userId: z.string().uuid(),
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive()
+  }))
+});
+```
+
+❌ Bad:
+```typescript
+// Variables & Functions (inconsistent)
+const CurrentUser = getCurrentUser();  # Wrong: PascalCase
+const valid_email = validate_email();  # Wrong: snake_case
+const CALCULATE_PRICE = () => {};      # Wrong: UPPER_CASE
+
+// Types & Interfaces (missing prefix)
+type User = {                         # Wrong: Missing T prefix
+  ID: string;                        # Wrong: UPPER_CASE
+  Email: string;                     # Wrong: PascalCase
+};
+
+interface OrderItem {                 # Wrong: Missing T prefix
+  product_id: string;               # Wrong: snake_case
+  Quantity: number;                 # Wrong: PascalCase
+}
+
+// Enums (inconsistent)
+enum OrderStatus {                    # Wrong: Missing E prefix
+  PENDING = 'PENDING',              # Wrong: All caps
+  Processing = 'Processing',        # Wrong: PascalCase value
+  completed = 'completed'           # Wrong: camelCase
+}
+
+// Schemas (inconsistent)
+const userSchema = z.object({         # Wrong: Missing S prefix
+  FirstName: z.string(),            # Wrong: PascalCase
+  last_name: z.string(),            # Wrong: snake_case
+  DOB: z.date()                     # Wrong: Abbreviation
+});
+```
+
+## Code Style
+
+### Type Safety
+- Always define explicit types for better maintainability
+- Always use TypeScript's type system to prevent runtime errors
+- Always make code intentions clear through typing
+
+✅ Good:
+```typescript
+async function getUser(id: string): Promise<TUser> {
+  const user = await db.users.findUnique({ where: { id } });
+  if (user == null) {
+    throw new Error('User not found');
+  }
+  return user;
+}
+```
+
+❌ Bad:
+```typescript
+async function getUser(id) {
+  const user = await db.users.findUnique({ where: { id } });
+  if (!user) throw new Error('User not found');
+  return user;
+}
+```
+
+### Null Checks
+- Always be explicit about null/undefined checks
+- Always handle edge cases clearly and consistently
+- Always prevent runtime null/undefined errors
+
+✅ Good:
+```typescript
+if (user == null) {
+  throw new Error('User is required');
+}
+
+const name = user.name ?? 'Anonymous';
+```
+
+❌ Bad:
+```typescript
+if (!user) {
+  throw new Error('User is required');
+}
+
+const name = user.name || 'Anonymous';
+```
+
+### Functions
+- Always keep functions focused and single-purpose
+- Always use function declarations for named functions
+- Always use arrow functions only for callbacks and inline functions
+
+✅ Good:
+```typescript
+function processUser(user: TUser): void {
+  // Implementation
+}
+
+users.map(user => user.name);
+```
+
+❌ Bad:
+```typescript
+const processUser = (user: TUser): void => {
+  // Implementation
+}
+
+users.map(function(user) { return user.name; });
+```
+
+### Conditionals
+- Always keep conditionals simple and flat
+- Always use early returns to reduce nesting
+- Always avoid deeply nested conditions
+
+✅ Good:
+```typescript
+// Early return pattern
+function processUser(user: TUser): void {
+  if (user == null) {
+    return;
+  }
+
+  if (!user.isActive) {
+    return;
+  }
+
+  processActiveUser(user);
+}
+
+// Simple boolean check
+function isValidUser(user: TUser): boolean {
+  return user != null && user.isActive;
+}
+```
+
+❌ Bad:
+```typescript
+// Deeply nested conditions
+function processUser(user: TUser): void {
+  if (user != null) {
+    if (user.isActive) {
+      if (user.permissions != null) {
+        if (user.permissions.canEdit) {
+          processActiveUser(user);
+        }
+      }
+    }
+  }
+}
+
+// Complex nested ternary
+const userName = user 
+  ? user.profile 
+    ? user.profile.name 
+      ? user.profile.name 
+      : 'No name'
+    : 'No profile'
+  : 'No user';
+```

README.md

@@ -20,13 +20,15 @@ A collection of open source libraries maintained by [builder.group](https://buil
 | [config](https://github.com/builder-group/community/blob/develop/packages/config)                                 | Collection of ESLint, Vite, and Typescript configurations                                                                                                                      | [`@blgc/config`](https://www.npmjs.com/package/@blgc/config)                     |
 | [elevenlabs-client](https://github.com/builder-group/community/blob/develop/packages/elevenlabs-client)           | Typesafe and straightforward fetch client for interacting with the ElevenLabs API using feature-fetch                                                                          | [`elevenlabs-client`](https://www.npmjs.com/package/elevenlabs-client)           |
 | [eprel-client](https://github.com/builder-group/community/blob/develop/packages/eprel-client)                     | Typesafe and straightforward fetch client for interacting with the European Product Registry for Energy Labelling (EPREL) API using feature-fetch                              | [`eprel-client`](https://www.npmjs.com/package/eprel-client)                     |
+| [feature-ecs](https://github.com/builder-group/community/blob/develop/packages/feature-ecs)                       | A flexible, typesafe, and performance-focused Entity Component System (ECS) library for TypeScript                                                                             | [`feature-ecs`](https://www.npmjs.com/package/feature-ecs)                       |
 | [feature-fetch](https://github.com/builder-group/community/blob/develop/packages/feature-fetch)                   | Straightforward, typesafe, and feature-based fetch wrapper supporting OpenAPI types                                                                                            | [`feature-fetch`](https://www.npmjs.com/package/feature-fetch)                   |
 | [feature-form](https://github.com/builder-group/community/blob/develop/packages/feature-form)                     | Straightforward, typesafe, and feature-based form library                                                                                                                      | [`feature-form`](https://www.npmjs.com/package/feature-form)                     |
 | [feature-logger](https://github.com/builder-group/community/blob/develop/packages/feature-logger)                 | Straightforward, typesafe, and feature-based logging library                                                                                                                   | [`feature-logger`](https://www.npmjs.com/package/feature-logger)                 |
 | [feature-react](https://github.com/builder-group/community/blob/develop/packages/feature-react)                   | ReactJs extension for the feature-state and feature-form library, providing hooks and features for ReactJs                                                                     | [`feature-state-react`](https://www.npmjs.com/package/feature-state-react)       |
 | [feature-state](https://github.com/builder-group/community/blob/develop/packages/feature-state)                   | Straightforward, typesafe, and feature-based state management library for ReactJs                                                                                              | [`feature-state`](https://www.npmjs.com/package/feature-state)                   |
 | [figma-connect](https://github.com/builder-group/community/blob/develop/packages/figma-connect)                   | Straightforward and typesafe wrapper around the communication between the app/ui (iframe) and plugin (sandbox) part of a Figma Plugin                                          | [`figma-connect`](https://www.npmjs.com/package/figma-connect)                   |
 | [google-webfonts-client](https://github.com/builder-group/community/blob/develop/packages/google-webfonts-client) | Typesafe and straightforward fetch client for interacting with the Google Web Fonts API using feature-fetch                                                                    | [`google-webfonts-client`](https://www.npmjs.com/package/google-webfonts-client) |
+| [head-metadata](https://github.com/builder-group/community/blob/develop/packages/head-metadata)                   | Typesafe and straightforward utility for extracting structured metadata (like `<meta>`, `<title>`, and `<link>`) from the `<head>` of an HTML document.                        | [`head-metadata`](https://www.npmjs.com/package/head-metadata)                   |
 | [openapi-ts-router](https://github.com/builder-group/community/blob/develop/packages/openapi-ts-router)           | Thin wrapper around the router of web frameworks like Express and Hono, offering OpenAPI typesafety and seamless integration with validation libraries such as Valibot and Zod | [`openapi-ts-router`](https://www.npmjs.com/package/openapi-ts-router)           |
 | [rollup-presets](https://github.com/builder-group/community/blob/develop/packages/rollup-presets)                 | A collection of opinionated, production-ready Rollup presets                                                                                                                   | [`rollup-presets`](https://www.npmjs.com/package/rollup-presets)                 |
 | [types](https://github.com/builder-group/community/blob/develop/packages/types)                                   | Shared TypeScript type definitions used across builder.group community packages                                                                                                | [`@blgc/types`](https://www.npmjs.com/package/@blgc/types)                       |
@@ -119,4 +121,4 @@ In short, we use objects because they are more flexible and allow for the kind o
 
 ### What Features?
 
-Think of features like components in an Entity Component System (ECS). Every feature based object (e.g., feature-state) has base functionality, and additional components (features) can be added to extend it. Unlike traditional ECS, we only adopt the concept of Components, without Systems or Entities. Each component contains the necessary functions to interact with the feature based object.
+Think of features like components in an Entity Component System (ECS). Every feature based object (e.g., feature-state) has base functionality, and additional components (features) can be added to extend it. Unlike traditional ECS, we only adopt the concept of Components, without Systems or Entities. Each component contains the necessary functions to interact with the feature based object.

examples/feature-ecs/vanilla/basic/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/feature-ecs/vanilla/basic/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + TS</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>