Netpress

Core package for the Netpress starter kit.

What It Provides

• Artisan-style CLI helpers
• Base classes for jobs, mail, requests, and models
• Observer registration utilities
• Shared container and exception primitives
• Laravel-inspired notification system (database, mail, log, queue) — see docs/notifications.md
• Realtime sockets with guarded rooms, auth middleware, and rate limits — see docs/sockets.md

Local Development

Install it as @admicaa/netpress.

Inside the current local workspace, the starter kit consumes it via file:../packages/netpress.

Database Notes

Netpress ships a shared migration and model/query abstraction that targets SQL drivers and MongoDB without requiring duplicate migrations in the common case.

Cross-Database Migrations

Use the shared migration API first:

export async function up(schema) {
  await schema.createTable('posts', (table) => {
    table.primaryKey('id');
    table.string('title').notNullable();
    table.foreignId('user_id').constrained('users').cascadeOnDelete();
    table.timestamps(false, true);
    table.softDeletes();
  });
}

Behavior is driver-aware:

• SQL drivers apply relational constraints, indexes, timestamps, JSON columns, decimals, enums, and other schema features through the SQL compiler.
• MongoDB creates the field, validator, and useful indexes, but skips SQL-only foreign-key enforcement.
• When MongoDB skips a relational constraint, Netpress logs a clear warning instead of silently pretending the constraint exists.

foreignId() Behavior

foreignId() now carries relational intent instead of assuming every driver can enforce the same thing.

• SQL: foreignId('user_id').constrained('users').cascadeOnDelete() compiles to an unsigned big integer column plus the foreign-key constraint.
• MongoDB: the same migration creates the user_id field, adds an index when helpful, infers the referenced key shape where it can, and logs that the actual foreign-key constraint was skipped.
• For MongoDB models inferred from shared migrations, constrained foreign ids map to ObjectId, Number, or a flexible scalar field depending on the referenced primary key.

Unsupported or Driver-Specific Schema Features

Some features only make sense on SQL backends:

• foreign(), references(), on(), constrained(), cascadeOnDelete(), and nullOnDelete() are enforced on SQL drivers.
• MongoDB safely ignores those relational constraints and warns during migration execution.
• unique() and index() are supported on both SQL and MongoDB.
• timestamps(), softDeletes(), json(), enum(), and decimal() are available through the shared schema abstraction, but the exact storage shape remains driver-specific.

Query Builder Differences

Common methods such as where(), orWhere(), whereIn(), whereNull(), whereNotNull(), orderBy(), limit(), offset(), and paginate() are shared across drivers.

Driver-specific behavior:

• SQL whereLike() uses bound LIKE clauses and upgrades to ILIKE on PostgreSQL.
• MongoDB whereLike() compiles to an escaped regex pattern to avoid regex injection.
• SQL full-text search uses native support where available and falls back to grouped LIKE matching on simpler dialects.
• MongoDB full-text search uses $text only when a text index is configured; otherwise Netpress raises a clear error and logs a warning.
• Relationship queries are supported through the shared relation API. Native SQL joins remain SQL-only by design.

Safe Raw Queries

Use raw SQL deliberately and always prefer bindings:

await DB.select('select * from users where email = ?', [email]);
await DB.statement('update users set last_login_at = ? where id = ?', [now, id]);

Security expectations:

• Query-builder raw fragments require bindings.
• SQL raw helpers reject dangerous fragments such as statement chaining or comment-based injection.
• Mongo query builders do not allow raw query fragments.