bunsane 0.4.0 → 0.5.1

package/core/validateEnv.ts

@@ -60,6 +60,16 @@ const envSchema = z
             .string()
             .regex(/^\d+$/, "DB_CONNECTION_TIMEOUT must be numeric (seconds)")
             .optional(),
+        DB_HEALTH_WRITE_TIMEOUT: z
+            .string()
+            .regex(/^\d+$/, "DB_HEALTH_WRITE_TIMEOUT must be numeric (milliseconds)")
+            .optional(),
+        HEALTH_DB_WRITE_PROBE: z
+            .enum(["true", "false"])
+            .optional(),
+        DB_DISABLE_PREPARE: z
+            .enum(["true", "false"])
+            .optional(),
     })
     .refine(
         (env) => {

package/database/DatabaseHelper.ts

@@ -156,7 +156,7 @@ export const CreateComponentTable = async () => {
         ) PARTITION BY LIST (type_id);`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id)`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id)`;
-        await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+        await ensureDataGinIndex();
         await db`CREATE INDEX IF NOT EXISTS idx_components_entity_type_deleted ON components (entity_id, type_id, deleted_at)`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_type_deleted ON components (type_id, deleted_at) WHERE deleted_at IS NULL`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_deleted_entity ON components (deleted_at, entity_id) WHERE deleted_at IS NULL`;
@@ -226,6 +226,30 @@ const dropOrphanedPartitionTables = async () => {
     }
 }
 
+/**
+ * The whole-`data` GIN index (`idx_components_data_gin`) only serves top-level
+ * JSONB containment / existence on the entire `data` column (`data @> ...`,
+ * `data ? key`, `data ?| / ?&`). The Query layer never emits those forms — it
+ * uses per-field text extraction (`data->>'field'`, served by per-field
+ * btree/expression indexes) and sub-path containment (`data->'field' @> ...`,
+ * served by per-field sub-path GIN). So this index is pure write amplification
+ * for framework queries AND it blocks HOT updates (any `data` write must touch
+ * it). It is therefore OPT-IN. Set BUNSANE_COMPONENTS_DATA_GIN=true only if you
+ * run raw SQL doing top-level containment on the whole component payload.
+ */
+const ensureDataGinIndex = async (): Promise<void> => {
+    if (process.env.BUNSANE_COMPONENTS_DATA_GIN === 'true') {
+        await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+        logger.info("Created whole-data GIN index idx_components_data_gin (BUNSANE_COMPONENTS_DATA_GIN=true).");
+    } else {
+        logger.info(
+            "Skipped whole-data GIN index idx_components_data_gin to cut write amplification and enable HOT updates " +
+            "(BUNSANE_COMPONENTS_DATA_GIN!=true). Per-field indexes serve all framework queries. A pre-existing DB " +
+            "that still has it can drop it manually: DROP INDEX CONCURRENTLY IF EXISTS idx_components_data_gin;"
+        );
+    }
+};
+
 export const CreateHashPartitionedComponentTable = async (partitionCount: number = 16) => {
     await db`CREATE TABLE IF NOT EXISTS components (
         id UUID,
@@ -249,7 +273,7 @@ export const CreateHashPartitionedComponentTable = async (partitionCount: number
 
     await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id)`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id)`;
-    await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+    await ensureDataGinIndex();
     await db`CREATE INDEX IF NOT EXISTS idx_components_entity_type_deleted ON components (entity_id, type_id, deleted_at)`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_type_deleted ON components (type_id, deleted_at) WHERE deleted_at IS NULL`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_deleted_entity ON components (deleted_at, entity_id) WHERE deleted_at IS NULL`;

package/database/index.ts

@@ -47,12 +47,26 @@ function createDatabase(): SQL {
     // workers (schedulers, outbox, migrations) can keep higher values.
     const connTimeout = parseInt(process.env.DB_CONNECTION_TIMEOUT ?? '30', 10);
 
+    // DB_DISABLE_PREPARE (opt-in): turn off Bun SQL's automatic server-side
+    // prepared statements (driver default `prepare: true`). REQUIRED behind
+    // PgBouncer in transaction pooling mode — each transaction may land on a
+    // different backend, so a prepared statement created on one connection is
+    // absent on the next, yielding `prepared statement "..." does not exist`
+    // errors that can poison the pooled client and wedge the write path. Costs
+    // a little per-query planning; negligible next to the failure it prevents.
+    const disablePrepare = process.env.DB_DISABLE_PREPARE === 'true';
+    if (disablePrepare) {
+        logger.info('Prepared statements disabled (DB_DISABLE_PREPARE=true) — required for PgBouncer transaction pooling');
+    }
+
     return new SQL({
         url,
         max,
         idleTimeout: 30000,
         maxLifetime: 600000,
         connectionTimeout: connTimeout,
+        // Only override when disabling; otherwise leave Bun's default (true).
+        ...(disablePrepare ? { prepare: false } : {}),
         onclose: (err) => {
             if (err) {
                 const errCode = (err as unknown as { code: string }).code;

package/database/sqlHelpers.ts

@@ -12,6 +12,8 @@ export function inList<T>(values: T[], paramIndex: number): { sql: string, param
   
   if (filteredValues.length === 0) return { sql: '()', params: [], newParamIndex: paramIndex };
   
-  const placeholders = Array.from({length: filteredValues.length}, (_, i) => `$${paramIndex + i}`).join(', ');
+  const n = filteredValues.length;
+  let placeholders = '';
+  for (let i = 0; i < n; i++) { placeholders += (i ? ', $' : '$') + (paramIndex + i); }
   return { sql: `(${placeholders})`, params: filteredValues, newParamIndex: paramIndex + filteredValues.length };
 }

package/gql/index.ts

@@ -149,8 +149,19 @@ export interface YogaInstanceOptions {
     maxComplexity?: number;
 }
 
+/**
+ * A schema provider may be a concrete `GraphQLSchema` or a factory returning
+ * the current schema. A factory is read per-request by Yoga, which lets the
+ * schema be swapped at runtime (e.g. ServiceRegistry.rebuildSchema()) without
+ * recreating the Yoga instance. Returning `null`/`undefined` falls back to the
+ * static placeholder schema.
+ */
+export type SchemaProvider =
+    | GraphQLSchema
+    | (() => GraphQLSchema | null | undefined);
+
 export function createYogaInstance(
-    schema?: GraphQLSchema,
+    schema?: SchemaProvider,
     plugins: Plugin[] = [],
     contextFactory?: (context: any) => any,
     options?: YogaInstanceOptions
@@ -188,16 +199,30 @@ export function createYogaInstance(
         yogaConfig.context = contextFactory;
     }
 
-    if (schema) {
+    // Memoized static placeholder schema. Kept stable so Yoga's per-schema
+    // internal caches (parse/validate) are not thrashed when a factory falls
+    // back to it across requests.
+    let fallbackSchema: GraphQLSchema | undefined;
+    const getFallback = (): GraphQLSchema => {
+        if (!fallbackSchema) {
+            fallbackSchema = createSchema({
+                typeDefs: staticTypeDefs,
+                resolvers: staticResolvers,
+            });
+        }
+        return fallbackSchema;
+    };
+
+    if (typeof schema === "function") {
+        // Factory form: read per request so runtime swaps reflect live.
+        // Stable refs keep Yoga's caches warm; only a changed ref re-primes.
+        yogaConfig.schema = () => schema() ?? getFallback();
+    } else if (schema) {
         yogaConfig.schema = schema;
-        return createYoga(yogaConfig);
     } else {
-        yogaConfig.schema = createSchema({
-            typeDefs: staticTypeDefs,
-            resolvers: staticResolvers,
-        });
-        return createYoga(yogaConfig);
+        yogaConfig.schema = getFallback();
     }
+    return createYoga(yogaConfig);
 }
 
 export const Upload = z.union([z.literal("Upload"), z.any()]);

package/gql/schema/index.ts

@@ -406,6 +406,12 @@ export function isSchemaInput(
 
 // ─── Validation ─────────────────────────────────────────────────────────────────
 
+// Keyed by schema object identity. Safe only when field builders inside the
+// schema are not mutated (via .required()/.optional()/.nullable()) after the
+// first validateInput call for that schema. Module-level schema constants
+// satisfy this constraint; inline schemas constructed per-call simply miss.
+const _zodCache = new WeakMap<object, ZodType>();
+
 export class SchemaValidationError extends Error {
     readonly fieldErrors: Array<{ path: string; message: string }>;
 
@@ -424,11 +430,16 @@ export function validateInput<T extends Record<string, SchemaType>>(
     data: unknown,
     operationName: string = "input",
 ): InferInput<T> {
-    const zodShape: Record<string, ZodType> = {};
-    for (const [key, field] of Object.entries(schema)) {
-        zodShape[key] = field.toZod();
+    let zodObject = _zodCache.get(schema);
+    if (!zodObject) {
+        const zodShape: Record<string, ZodType> = {};
+        for (const [key, field] of Object.entries(schema)) {
+            zodShape[key] = field.toZod();
+        }
+        zodObject = z.object(zodShape);
+        _zodCache.set(schema, zodObject);
     }
-    const result = z.object(zodShape).safeParse(data);
+    const result = zodObject.safeParse(data);
     if (result.success) {
         return result.data as InferInput<T>;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.4.0",
+    "version": "0.5.1",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -862,7 +862,11 @@ export class ComponentInclusionNode extends QueryNode {
                     } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
                         // IN/NOT IN comparison - handle arrays properly
                         if (Array.isArray(filter.value) && filter.value.length > 0) {
-                            const placeholders = Array.from({length: filter.value.length}, (_, i) => `$${context.addParam(filter.value[i])}`).join(', ');
+                            let placeholders = '';
+                            for (let i = 0; i < filter.value.length; i++) {
+                                if (i) placeholders += ', ';
+                                placeholders += '$' + context.addParam(filter.value[i]);
+                            }
                             condition = `${jsonPath} ${filter.operator} (${placeholders})`;
                         } else if (Array.isArray(filter.value) && filter.value.length === 0) {
                             // Empty array: IN () is always false, NOT IN () is always true

package/query/OrNode.ts

@@ -357,13 +357,7 @@ export class OrNode extends QueryNode {
                 WHERE EXISTS (
                     SELECT 1 FROM ${componentTableName} c
                     WHERE c.entity_id = base.id
-                    AND c.type_id = $${componentIdParamIndex}                    AND c.deleted_at IS NULL
-                    AND c.created_at = (
-                        SELECT MAX(c2.created_at)
-                        FROM ${componentTableName} c2
-                        WHERE c2.entity_id = c.entity_id
-                        AND c2.type_id = $${componentIdParamIndex}                        AND c2.deleted_at IS NULL
-                    )`;
+                    AND c.type_id = $${componentIdParamIndex}                    AND c.deleted_at IS NULL`;
             } else {
                 // Use original query without base
                 const componentTableName = this.getComponentTableName(componentId);
@@ -374,13 +368,7 @@ export class OrNode extends QueryNode {
                 AND EXISTS (
                     SELECT 1 FROM ${componentTableName} c
                     WHERE c.entity_id = ec.entity_id
-                    AND c.type_id = $${componentIdParamIndex}                    AND c.deleted_at IS NULL
-                    AND c.created_at = (
-                        SELECT MAX(c2.created_at)
-                        FROM ${componentTableName} c2
-                        WHERE c2.entity_id = c.entity_id
-                        AND c2.type_id = $${componentIdParamIndex}                        AND c2.deleted_at IS NULL
-                    )`;
+                    AND c.type_id = $${componentIdParamIndex}                    AND c.deleted_at IS NULL`;
             }
 
             context.params.push(componentId);

package/query/Query.ts

@@ -21,6 +21,40 @@ import { getMembershipSource } from "./membershipSource";
 const DEFAULT_QUERY_LIMIT = parseInt(process.env.BUNSANE_DEFAULT_QUERY_LIMIT ?? '10000', 10);
 let warnedDefaultLimit = false;
 
+// Gated once — dev keeps param diagnostics, production skips the loop entirely.
+const DEBUG_PARAMS = process.env.NODE_ENV !== 'production';
+
+// Shared across all TypedEntity instances — avoids one closure allocation per row.
+// Must be called as a method (entity.getTyped(Ctor)) so `this` resolves correctly.
+async function sharedGetTyped(
+    this: any,
+    ctor: any
+): Promise<any> {
+    const data = await this.get(ctor);
+    if (!data) {
+        throw new Error(`Component ${ctor.name} not found on entity ${this.id}, but it was expected from query`);
+    }
+    return data;
+}
+
+// Hoisted descriptor for _queriedComponents — non-enumerable by design (hidden from
+// Object.keys / spreads). Descriptor is reused; only `value` is patched per row.
+const queriedComponentsDescriptor: PropertyDescriptor = {
+    value: undefined as any,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+};
+
+// getTyped stays non-enumerable like the original defineProperty version; the value
+// never varies, so the descriptor is fully static.
+const getTypedDescriptor: PropertyDescriptor = {
+    value: sharedGetTyped,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+};
+
 export type FilterOperator = "=" | ">" | "<" | ">=" | "<=" | "!=" | "LIKE" | "ILIKE" | "IN" | "NOT IN" | string;
 
 export const FilterOp = {
@@ -786,34 +820,16 @@ AND c.deleted_at IS NULL`;
         // Create typed entity wrapper
         const typedEntity = entity as TypedEntity<TComponents>;
 
-        // Define componentData property
-        Object.defineProperty(typedEntity, 'componentData', {
-            value: componentData as ComponentRecord<TComponents>,
-            writable: false,
-            enumerable: true
-        });
+        // Plain assignment — enumerable: true matches prior behavior; no defineProperty overhead.
+        (typedEntity as any).componentData = componentData as ComponentRecord<TComponents>;
 
-        // Define _queriedComponents property for runtime reflection
-        Object.defineProperty(typedEntity, '_queriedComponents', {
-            value: componentCtors as unknown as TComponents,
-            writable: false,
-            enumerable: false
-        });
+        // _queriedComponents must stay non-enumerable (hidden from Object.keys / spreads).
+        queriedComponentsDescriptor.value = componentCtors as unknown as TComponents;
+        Object.defineProperty(typedEntity, '_queriedComponents', queriedComponentsDescriptor);
+        queriedComponentsDescriptor.value = undefined; // don't retain ref
 
-        // Define getTyped method
-        Object.defineProperty(typedEntity, 'getTyped', {
-            value: async function<T extends TComponents[number]>(
-                ctor: T
-            ): Promise<T extends ComponentConstructor<infer C> ? C extends BaseComponent ? ComponentDataType<C> : never : never> {
-                const data = await entity.get(ctor as any);
-                if (!data) {
-                    throw new Error(`Component ${(ctor as any).name} not found on entity ${entity.id}, but it was expected from query`);
-                }
-                return data as any;
-            },
-            writable: false,
-            enumerable: false
-        });
+        // Shared function — one allocation per module, not per row.
+        Object.defineProperty(typedEntity, 'getTyped', getTypedDescriptor);
 
         return typedEntity;
     }
@@ -878,13 +894,15 @@ AND c.deleted_at IS NULL`;
         // originate from saved entities. PG emits a clear error at
         // execution time if a UUID cast meets an empty string.
 
-        // Validate parameters before execution
-        for (let i = 0; i < result.params.length; i++) {
-            if (result.params[i] === undefined || result.params[i] === null) {
-                console.error(`❌ Query parameter $${i + 1} is undefined/null`);
-                console.error(`SQL: ${result.sql}`);
-                console.error(`All params: ${JSON.stringify(result.params)}`);
-                throw new Error(`Query parameter $${i + 1} is undefined/null. SQL: ${result.sql.substring(0, 100)}...`);
+        // Validate parameters before execution (dev only — skipped in production)
+        if (DEBUG_PARAMS) {
+            for (let i = 0; i < result.params.length; i++) {
+                if (result.params[i] === undefined || result.params[i] === null) {
+                    console.error(`❌ Query parameter $${i + 1} is undefined/null`);
+                    console.error(`SQL: ${result.sql}`);
+                    console.error(`All params: ${JSON.stringify(result.params)}`);
+                    throw new Error(`Query parameter $${i + 1} is undefined/null. SQL: ${result.sql.substring(0, 100)}...`);
+                }
             }
         }
 

package/service/ServiceRegistry.ts

@@ -14,6 +14,7 @@ export class ServiceRegistry {
 
     private services: Map<string, BaseService> = new Map();
     private schema: GraphQLSchema | null = null;
+    private schemaVersion: number = 0;
     private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
 
 
@@ -29,13 +30,7 @@ export class ServiceRegistry {
         this.phaseListener = (event: PhaseChangeEvent) => {
             switch(event.detail) {
                 case ApplicationPhase.SYSTEM_REGISTERING: {
-                    const servicesArray = Array.from(this.services.values());
-
-                    const result = generateGraphQLSchemaV2(servicesArray, {
-                        enableArchetypeOperations: false
-                    });
-
-                    this.schema = result.schema;
+                    this.rebuildSchema();
                     ApplicationLifecycle.setPhase(ApplicationPhase.SYSTEM_READY);
                     break;
                 };
@@ -74,6 +69,30 @@ export class ServiceRegistry {
     public getSchema(): GraphQLSchema | null {
         return this.schema;
     }
+
+    public getSchemaVersion(): number {
+        return this.schemaVersion;
+    }
+
+    /**
+     * Re-generate the GraphQL schema from the currently registered services
+     * and swap the stored reference. The live Yoga instance reads the schema
+     * via a factory (see graphqlSetup), so the next request observes the new
+     * schema without recreating Yoga or restarting the process.
+     *
+     * This is the Phase 0 "live re-weave" primitive: register a service (or
+     * mutate one's __graphqlOperations) then call this to reflect it.
+     * Returns the new schema (or null if generation produced none).
+     */
+    public rebuildSchema(): GraphQLSchema | null {
+        const servicesArray = Array.from(this.services.values());
+        const result = generateGraphQLSchemaV2(servicesArray, {
+            enableArchetypeOperations: false
+        });
+        this.schema = result.schema;
+        this.schemaVersion++;
+        return this.schema;
+    }
 }
 
 export default ServiceRegistry.instance;