[!CAUTION]

⚠️ ALPHA VERSION — DO NOT USE IN PRODUCTION

DarkStar is in early alpha. APIs will change without notice. The package is not stable — use at your own risk.

[!WARNING]

🧪 CUSTOM ORM — BUILT FROM SCRATCH

DarkStar uses a custom ORM inspired by Eloquent, built from scratch for Node.js. It is not Prisma, TypeORM or Sequelize. Relationships (hasOne, hasMany, belongsTo, belongsToMany) and eager loading (with()) are implemented. Transactions are not yet available.

[!NOTE] 📦 DarkStar is published on npm as @darkstar-cli/cli. Install with npm install -g @darkstar-cli/cli.

🪐 DarkStar — CLI

"Forged in the void. Built to last."

Inspired by the elegance of Laravel — reimagined for the Node.js universe.

What is this package?

@darkstar-cli/cli is the command-line tool for the DarkStar framework. It:

• Creates projects (darkstar new)
• Generates code (darkstar forge make:*)
• Manages the database (darkstar forge db:*)
• Runs the dev server (darkstar serve)

The ORM and core are separate packages:

• @darkstar-cli/orm — documentation
• @darkstar-cli/core — Express-based HTTP layer

Commands

| Command | Description | |---|---| | darkstar new <name> | Creates a new project | | darkstar serve | Starts the development server | | darkstar forge make:api <Name> | Generates controller + service + repository + model + routes + schema + middleware | | darkstar forge make:controller <Name> | Generates a Controller | | darkstar forge make:service <Name> | Generates a Service | | darkstar forge make:repository <Name> | Generates a Repository | | darkstar forge make:model <Name> | Generates a Model | | darkstar forge make:migration <Name> | Generates a Migration | | darkstar forge make:seeder <Name> | Generates a Seeder (reads fields from the migration) | | darkstar forge make:schema <Name> | Generates a Schema | | darkstar forge make:middleware <Name> | Generates a Middleware | | darkstar forge make:util <Name> | Generates omitPassword and twoFactor utils | | darkstar forge make:security | Generates RateLimitMiddleware with 22 ready-made limiters | | darkstar forge make:deps [names...] | Installs optional dependencies (bcrypt, jwt, zod, etc) | | darkstar forge db:create | Creates the database | | darkstar forge db:migrate | Runs pending migrations | | darkstar forge db:rollback | Rolls back the last migration | | darkstar forge db:seed | Seeds the database |

Full usage docs: see the main repository.

⚠️ Known limitations

DarkStar is in early alpha. The limitations below are known and will be addressed in future releases.

CLI

• darkstar new uses latest for @darkstar-cli/* — the generated package.json references @darkstar-cli/core and @darkstar-cli/orm as latest. New projects always pull the newest version, which may include breaking changes while DarkStar is in alpha.
• darkstar serve runs npm run dev — assumes the project has a dev script in package.json. If you rename it, darkstar serve will fail.
• Automatic seeder registration depends on the comment // registre seus seeders aqui — if this comment is removed or modified in DatabaseSeeder.ts, make:seeder will not register the new seeder automatically.
• db:seed runs tsx from the project's node_modules/.bin/ — if tsx is not installed locally (via npm install -D tsx), the seeder will fail. darkstar new already installs it.

IoC Container

• Dependency resolution is based on constructor parameter names — the container parses the constructor source code as a string to infer dependencies. This breaks when code is minified, bundled or compiled in a way that renames parameters. Do not use with bundlers that mangle variable names (e.g. esbuild with minifyIdentifiers: true).
• No circular dependency detection — circular dependencies will cause a stack overflow with no useful error message.

Validation

• UserSchema is an empty object — schemas generated by make:schema and make:api are stubs with no validation logic. Integrate Zod or Joi manually for now.

Two-Factor Authentication

• twoFactor.ts is not RFC 6238 compliant — the generated util uses crypto.randomInt to produce a one-time code, but has no time window, HMAC or shared secret. It is suitable only as a placeholder. For production 2FA, use otplib.

🔒 Security checklist

The stubs generated by make:api are skeletons only. Before going to production, you must:

• [ ] Hash passwords before saving (bcrypt.hash(password, 10))
• [ ] Omit sensitive fields from responses (password, token, secret)
• [ ] Validate user input (Zod/Joi in make:schema)
• [ ] Apply rate limiting (make:security already generates the limiters)
• [ ] Configure CORS
• [ ] Use HTTPS
• [ ] Never commit .env

DarkStar does not do this automatically because every project has different requirements. The framework gives you the structure; you decide the security policy.

⚠️ Known pitfalls in generated stubs

The make:api command generates a working MVC skeleton, but it is intentionally minimal. Watch out for these common issues:

• password is returned in API responses — the generated controller strips it via static hidden (Laravel-style), but related models are not stripped automatically. Handle it in the controller for nested relations.
• POST stores the password as plain text — the generated store() method does no hashing. Add bcrypt.hash() in the controller or service layer.
• update() returns the number of affected rows, not the updated record — re-fetch the record if you need the new values.
• UserSchema is an empty object — no validation is applied. Integrate Zod or Joi manually.

These are not framework bugs — they are conscious design decisions. DarkStar ships with the structure, not the policy.

Inspirations

• Laravel — for the elegance and productivity
• Pandorum — for the idea of forging something new in the void of space
• Constellation CLI — same spirit of automating what is repetitive

🪐 DarkStar — Open Source