@warpfx/server 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -66,10 +66,20 @@ interface ColumnDef {
     /** Default value for this column when inserting a row without it. */
     default?: unknown;
 }
+/** Table access mode for client sync. */
+type AccessMode = "private" | "public";
 /** Table definition in a warp.schema.json. */
 interface TableDef {
     /** Column definitions keyed by column name. */
     columns: Record<string, ColumnDef>;
+    /**
+     * Client access mode — controls automatic sync to players.
+     *
+     * - `"private"` — Only the owning player receives their rows (scope = primary key).
+     * - `"public"` — All connected players receive all rows.
+     * - Omitted — Server-only, not synced to clients.
+     */
+    access?: AccessMode;
 }
 /** The full warp.schema.json format. */
 interface WarpSchema {
@@ -84,22 +94,22 @@ interface WarpSchema {
 }
 
 /**
- * @warp/server — Typed SDK for Warp server-side module development.
+ * @warpfx/server — Server-side SDK for Warp module development.
  *
- * Provides type-safe access to the Warp core API. Under the hood,
- * all calls go through FiveM's resource exports to the 'warp' resource.
+ * Clean, minimal API for building FiveM server features with Warp.
+ * All calls delegate to the Warp core via FiveM resource exports.
  *
  * Usage:
- *   import { onReady, provide, use, getEvents } from '@warp/server';
+ *   import { action, fn, command, error, table } from '@warpfx/server';
+ *   import { accounts } from './db'; // auto-generated from schema
  *
- *   onReady(() => {
- *     const events = getEvents();
- *     events.on('player:spawned', (data) => { ... });
- *     provide('economy', new EconomyService());
+ *   action('deposit', async (player, { amount }) => {
+ *     const account = accounts.find(player.citizenId);
+ *     accounts.update(player.citizenId, { balance: account.balance + amount });
  *   });
  */
-/** Player lifecycle event data. */
-interface PlayerEventContext {
+/** Player context passed to action/function handlers. */
+interface Player {
     /** FiveM server-side player ID. */
     source: number;
     /** Citizen ID (license identifier). */
@@ -124,216 +134,184 @@ interface PlayerRow {
 type PlayerState = "connecting" | "connected" | "spawned";
 /** Player entity with ECS component access. */
 interface PlayerEntity {
-    /** FiveM server-side player ID. */
     readonly source: number;
-    /** Citizen ID (license identifier). */
     readonly citizenId: string;
-    /** Display name. */
     readonly name: string;
-    /** Discord identifier (e.g. "discord:123456789"), if linked. */
     readonly discordId: string | undefined;
-    /** Steam identifier (e.g. "steam:110000..."), if linked. */
     readonly steamId: string | undefined;
-    /** Current lifecycle state. */
     readonly state: PlayerState;
-    /** Get a component attached to this player. */
     getComponent<T>(component: string): T | undefined;
-    /** Attach or replace a component on this player. */
     setComponent<T>(component: string, data: T): void;
-    /** Check if this player has a specific component. */
     hasComponent(component: string): boolean;
-    /** Remove a component from this player. */
     removeComponent(component: string): boolean;
 }
 /** Typed event bus for server-side and network communication. */
 interface ServerEventBus<TMap extends Record<string, any> = Record<string, any>> {
-    /** Subscribe to a local event. Returns an unsubscribe function. */
     on<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): () => void;
-    /** Unsubscribe from a local event. */
     off<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): void;
-    /** Emit a local event to all subscribers. */
     emit<K extends string & keyof TMap>(event: K, data: TMap[K]): void;
-    /** Send an event to a specific client. */
     emitClient<K extends string & keyof TMap>(event: K, target: number, data: TMap[K]): void;
-    /** Broadcast an event to all connected clients. */
     emitAllClients<K extends string & keyof TMap>(event: K, data: TMap[K]): void;
-    /** Listen for events from clients. Returns an unsubscribe function. */
     onClient<K extends string & keyof TMap>(event: K, handler: (source: number, data: TMap[K]) => void): () => void;
-    /** Unsubscribe from a client event. */
     offClient<K extends string & keyof TMap>(event: K, handler: (source: number, data: TMap[K]) => void): void;
 }
 /** ECS-inspired entity component store. */
 interface EntityStore {
-    /** Attach a component to an entity. */
     attach<T>(entityId: string, component: string, data: T): void;
-    /** Get a component from an entity. Returns undefined if not found. */
     get<T>(entityId: string, component: string): T | undefined;
-    /** Remove a component from an entity. */
     detach(entityId: string, component: string): boolean;
-    /** Remove all components for an entity. */
     removeEntity(entityId: string): void;
-    /** Check if an entity has a specific component. */
     has(entityId: string, component: string): boolean;
-    /** Iterate all entities that have a specific component. */
     query<T>(component: string): IterableIterator<[string, T]>;
 }
-/**
- * Register a callback to run when Warp is fully booted.
- * If Warp is already ready, the callback fires immediately.
- * All other SDK functions should be called inside this callback.
- */
-declare function onReady(cb: () => void): void;
-/** Check if Warp has finished booting. */
-declare function isReady(): boolean;
-/** Register a service that other modules can resolve via use(). */
-declare function provide<T>(token: string, service: T): void;
-/** Resolve a service registered by another module. */
-declare function use<T = unknown>(token: string): T;
-/** Get the shared event bus instance. */
-declare function getEvents<TMap extends Record<string, any> = Record<string, any>>(): ServerEventBus<TMap>;
-/** Get the shared entity component store. */
-declare function getEntities(): EntityStore;
-/** Find a player by citizenId from the database cache. */
-declare function getPlayer(citizenId: string): PlayerRow | null;
-/** Get all cached players. */
-declare function getPlayers(): PlayerRow[];
-/**
- * Get the player entity for a citizenId.
- * Returns the entity with lifecycle state and component access.
- */
-declare function getEntity(citizenId: string): PlayerEntity | null;
-/**
- * Transition a player to the "spawned" state.
- * Call after character selection (e.g. from a multichar module).
- * Fires all onPlayerSpawned hooks.
- */
-declare function spawnPlayer(citizenId: string): void;
-/** Register a callback for when a player connects (database confirmed). */
-declare function onPlayerConnect(cb: (player: PlayerEventContext) => void): void;
-/** Register a callback for when a player spawns (character selected). */
-declare function onPlayerSpawned(cb: (player: PlayerEventContext) => void): void;
-/** Register a callback for when a player disconnects. */
-declare function onPlayerDisconnect(cb: (player: PlayerEventContext) => void): void;
-/**
- * Get the database bridge for direct table and reducer access.
- * Advanced — most modules should use the event bus and DI instead.
- */
-declare function getBridge(): any;
-/** Subscribe to database tables. Call inside onReady(). */
-declare function subscribe(queries: string[]): Promise<void>;
-/** Sync configuration for a table. */
-interface SyncConfig {
-    /** Who receives updates for this table. */
-    to: "owner" | "all";
-    /** Column name for owner filtering (required when to: 'owner'). */
-    scope?: string;
-    /** Primary key column for row identity (defaults to 'id'). */
-    key?: string;
+/** Table handle for typed database operations. */
+interface Table<T = any> {
+    /** Find a row by primary key. */
+    find(primaryKey: any): T | null;
+    /** Get all rows in the table. */
+    all(): T[];
+    /** Insert a new row. */
+    insert(data: T): Promise<void>;
+    /** Update an existing row by primary key (partial update). */
+    update(primaryKey: any, data: Partial<T>): Promise<void>;
+    /** Delete a row by primary key. */
+    delete(primaryKey: any): Promise<void>;
 }
-/** Context passed to action handlers. */
-interface ActionContext {
-    /** FiveM server-side player ID. */
-    source: number;
-    /** Player's citizen ID (license identifier). */
-    citizenId: string;
-    /** Player's display name. */
+/** Parameter hint shown in command autocomplete. */
+interface CommandParam {
     name: string;
-    /** Discord identifier (e.g. "discord:123456789"), if linked. */
-    discordId?: string;
-    /** Steam identifier (e.g. "steam:110000..."), if linked. */
-    steamId?: string;
-    /** Database table accessors (read-only). */
-    db: any;
-    /** Database reducer proxy (for mutations). */
-    reducers: any;
+    help?: string;
+}
+/** Options for command(). */
+interface CommandOptions {
+    description?: string;
+    ace?: string;
+    canUse?: (source: number) => boolean;
+    params?: CommandParam[];
+}
+/** Action error received from the server. */
+interface ActionError {
+    action: string;
+    code: string;
+    message: string;
+}
+/** Describes a single table row change. */
+interface TableChange<T = any> {
+    /** The type of change. */
+    type: "insert" | "update" | "delete";
+    /** The current row (new on insert/update, deleted row on delete). */
+    row: T;
+    /** The previous row (on update only, undefined otherwise). */
+    oldRow?: T;
 }
-/** Action handler function. */
-type ActionHandler = (ctx: ActionContext, payload: any) => Promise<void> | void;
-/** Server function handler — returns a value back to the caller. */
-type FunctionHandler<T = any> = (ctx: ActionContext, payload: any) => Promise<T> | T;
 /**
- * Register a table for automatic sync to clients.
+ * Register an action handler that clients can invoke.
  *
- * The sync engine subscribes to SpacetimeDB table changes and routes
- * updates to the correct players based on the config. Call inside onReady().
+ * Actions are fire-and-forget mutations — the client sends data,
+ * the server validates and mutates, state syncs back automatically.
  *
  * @example
- * registerSync('inventory', { to: 'owner', scope: 'ownerId', key: 'id' });
- * registerSync('itemDefinitions', { to: 'all', key: 'name' });
+ * action('deposit', async (player, { amount }) => {
+ *   const account = accounts.find(player.citizenId);
+ *   accounts.update(player.citizenId, { balance: account.balance + amount });
+ * });
  */
-declare function registerSync(table: string, config: SyncConfig): void;
+declare function action(name: string, handler: (player: Player, payload: any) => Promise<void> | void): void;
 /**
- * Register an action handler that clients can invoke via useAction().
+ * Register a server function that clients can call and await a result.
  *
- * Actions are the only entry point for client-initiated mutations.
- * The sync engine handles security, error routing, and state updates.
+ * Unlike actions (fire-and-forget), functions return a value to the caller.
+ * Use for request/response patterns like data fetches or validations.
  *
  * @example
- * registerAction('inventory:moveItem', async (ctx, { itemId, toSlot }) => {
- *   await ctx.reducers.moveItem(ctx.citizenId, itemId, toSlot);
+ * fn('getBalance', async (player, { targetId }) => {
+ *   const account = accounts.find(targetId);
+ *   return { balance: account?.balance ?? 0 };
  * });
  */
-declare function registerAction(name: string, handler: ActionHandler): void;
+declare function fn<T = any>(name: string, handler: (player: Player, payload: any) => Promise<T> | T): void;
 /**
- * Register a server function that clients can call and await a result.
- *
- * Unlike actions (fire-and-forget mutations), functions return a value
- * to the caller. Use for request/response patterns like data fetches,
- * calculations, or validations that need a result.
+ * Register a chat command with optional autocomplete.
  *
  * @example
- * registerFunction('economy:getBalance', async (ctx) => {
- *   const account = ctx.db.economy_accounts.citizenId.find(ctx.citizenId);
- *   return { balance: account?.balance ?? 0 };
+ * command('balance', (player) => {
+ *   const account = accounts.find(player.citizenId);
+ *   player.notify(`Balance: $${account.balance}`);
  * });
+ *
+ * command('give', {
+ *   description: 'Give money to a player',
+ *   params: [{ name: 'id' }, { name: 'amount' }],
+ * }, (player, args) => { ... });
  */
-declare function registerFunction<T = any>(name: string, handler: FunctionHandler<T>): void;
+declare function command(name: string, handlerOrOptions: CommandOptions | ((player: Player, args: string[], raw: string) => void), handler?: (player: Player, args: string[], raw: string) => void): void;
 /**
- * Typed error for action handlers. Thrown errors with a `code` property
- * are sent to the client as structured error messages.
+ * Create an error to throw from action/function handlers.
+ * The error is sent back to the client with a structured code and message.
  *
  * @example
- * throw new WarpError('ITEM_NOT_FOUND', 'That item no longer exists');
+ * throw error('NO_ACCOUNT', 'No account found');
  */
-declare class WarpError extends Error {
-    code: string;
-    constructor(code: string, message?: string);
-}
-/** Parameter hint shown in command autocomplete. */
-interface CommandParam {
-    /** Parameter name displayed in the suggestion (e.g. "id", "reason"). */
-    name: string;
-    /** Optional help text for the parameter. */
-    help?: string;
-}
-/** Options for registerCommand(). */
-interface CommandOptions {
-    /** Short description shown in autocomplete. */
-    description?: string;
-    /** ACE permission required — players without it won't see the command. */
-    ace?: string;
-    /** Custom permission predicate (overrides ace check when provided). */
-    canUse?: (source: number) => boolean;
-    /** Parameter hints shown in autocomplete. */
-    params?: CommandParam[];
-}
+declare function error(code: string, message?: string): Error;
+/**
+ * Get a table handle for database operations.
+ *
+ * The table name must be the full prefixed name (e.g. 'economy_accounts').
+ * For auto-generated handles with types, use the generated `db.ts` instead.
+ *
+ * @example
+ * const accounts = table<Account>('economy_accounts');
+ * const account = accounts.find(citizenId);
+ * await accounts.update(citizenId, { balance: 500 });
+ */
+declare function table<T = any>(name: string): Table<T>;
 /**
- * Register a command with autocomplete support.
+ * React to any change in a database table.
  *
- * Players see matching commands as they type in the chat input,
- * filtered by permission. The handler receives the standard FiveM
- * command arguments.
+ * Fires on insert, update, or delete — regardless of what caused the change
+ * (action, another module, migration, Studio edit). Works on all tables
+ * including server-only tables without an `access` field.
  *
  * @example
- * registerCommand('arrest', {
- *   description: 'Arrest a nearby player',
- *   ace: 'police.arrest',
- *   params: [{ name: 'id', help: 'Player server ID' }],
- * }, (source, args) => {
- *   const targetId = parseInt(args[0], 10);
- *   // ...
+ * onTableChange<Account>('economy_accounts', (change) => {
+ *   if (change.type === 'update' && change.row.balance < 0) {
+ *     accounts.update(change.row.citizenId, { frozen: true });
+ *   }
  * });
  */
-declare function registerCommand(name: string, options: CommandOptions, handler: (source: number, args: string[], rawCommand: string) => void): void;
+declare function onTableChange<T = any>(table: string, handler: (change: TableChange<T>) => void): void;
+/**
+ * Register a callback to run when Warp is fully booted.
+ * If Warp is already ready, the callback fires immediately.
+ */
+declare function onReady(cb: () => void): void;
+/** Check if Warp has finished booting. */
+declare function isReady(): boolean;
+/** Register a service that other modules can resolve via use(). */
+declare function provide<T>(token: string, service: T): void;
+/** Resolve a service registered by another module. */
+declare function use<T = unknown>(token: string): T;
+/** Get the shared event bus instance. */
+declare function getEvents<TMap extends Record<string, any> = Record<string, any>>(): ServerEventBus<TMap>;
+/** Get the shared entity component store. */
+declare function getEntities(): EntityStore;
+/** Find a player by citizenId from the database cache. */
+declare function getPlayer(citizenId: string): PlayerRow | null;
+/** Get all cached players. */
+declare function getPlayers(): PlayerRow[];
+/** Get the player entity for a citizenId. */
+declare function getEntity(citizenId: string): PlayerEntity | null;
+/** Transition a player to the "spawned" state. */
+declare function spawnPlayer(citizenId: string): void;
+/** Register a callback for when a player connects. */
+declare function onPlayerConnect(cb: (player: Player) => void): void;
+/** Register a callback for when a player spawns. */
+declare function onPlayerSpawned(cb: (player: Player) => void): void;
+/** Register a callback for when a player disconnects. */
+declare function onPlayerDisconnect(cb: (player: Player) => void): void;
+/** Get the database bridge for direct table and reducer access. */
+declare function getBridge(): any;
+/** Subscribe to database tables. */
+declare function subscribe(queries: string[]): Promise<void>;
 
-export { type ActionContext, type ActionHandler, type ColumnDef, type ColumnType, type CommandOptions, type CommandParam, type EntityStore, type FunctionHandler, type PlayerEntity, type PlayerEventContext, type PlayerRow, type PlayerState, type ServerEventBus, type SyncConfig, type TableDef, WarpError, type WarpSchema, getBridge, getEntities, getEntity, getEvents, getPlayer, getPlayers, isReady, onPlayerConnect, onPlayerDisconnect, onPlayerSpawned, onReady, provide, registerAction, registerCommand, registerFunction, registerSync, spawnPlayer, subscribe, use };
+export { type AccessMode, type ActionError, type ColumnDef, type ColumnType, type CommandOptions, type CommandParam, type EntityStore, type Player, type PlayerEntity, type PlayerRow, type PlayerState, type ServerEventBus, type Table, type TableChange, type TableDef, type WarpSchema, action, command, error, fn, getBridge, getEntities, getEntity, getEvents, getPlayer, getPlayers, isReady, onPlayerConnect, onPlayerDisconnect, onPlayerSpawned, onReady, onTableChange, provide, spawnPlayer, subscribe, table, use };

package/dist/index.js

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  WarpError: () => WarpError,
+  action: () => action,
+  command: () => command,
+  error: () => error,
+  fn: () => fn,
   getBridge: () => getBridge,
   getEntities: () => getEntities,
   getEntity: () => getEntity,
@@ -32,19 +35,39 @@ __export(index_exports, {
   onPlayerDisconnect: () => onPlayerDisconnect,
   onPlayerSpawned: () => onPlayerSpawned,
   onReady: () => onReady,
+  onTableChange: () => onTableChange,
   provide: () => provide,
-  registerAction: () => registerAction,
-  registerCommand: () => registerCommand,
-  registerFunction: () => registerFunction,
-  registerSync: () => registerSync,
   spawnPlayer: () => spawnPlayer,
   subscribe: () => subscribe,
+  table: () => table,
   use: () => use
 });
 module.exports = __toCommonJS(index_exports);
 function warp() {
   return globalThis.exports["warp"];
 }
+function action(name, handler) {
+  warp().action(name, handler);
+}
+function fn(name, handler) {
+  warp().fn(name, handler);
+}
+function command(name, handlerOrOptions, handler) {
+  if (typeof handlerOrOptions === "function") {
+    warp().command(name, {}, handlerOrOptions);
+  } else {
+    warp().command(name, handlerOrOptions, handler);
+  }
+}
+function error(code, message) {
+  return warp().error(code, message);
+}
+function table(name) {
+  return warp().table(name);
+}
+function onTableChange(table2, handler) {
+  warp().onTableChange(table2, handler);
+}
 function onReady(cb) {
   warp().onReady(cb);
 }
@@ -90,28 +113,12 @@ function getBridge() {
 function subscribe(queries) {
   return warp().subscribe(queries);
 }
-function registerSync(table, config) {
-  warp().registerSync(table, config);
-}
-function registerAction(name, handler) {
-  warp().registerAction(name, handler);
-}
-function registerFunction(name, handler) {
-  warp().registerFunction(name, handler);
-}
-var WarpError = class extends Error {
-  constructor(code, message) {
-    super(message ?? code);
-    this.code = code;
-    this.name = "WarpError";
-  }
-};
-function registerCommand(name, options, handler) {
-  warp().registerCommand(name, options, handler);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  WarpError,
+  action,
+  command,
+  error,
+  fn,
   getBridge,
   getEntities,
   getEntity,
@@ -123,12 +130,10 @@ function registerCommand(name, options, handler) {
   onPlayerDisconnect,
   onPlayerSpawned,
   onReady,
+  onTableChange,
   provide,
-  registerAction,
-  registerCommand,
-  registerFunction,
-  registerSync,
   spawnPlayer,
   subscribe,
+  table,
   use
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpfx/server",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Warp Framework SDK for server-side FiveM module development",
   "keywords": [
     "fivem",