@lunora/server 1.0.0-alpha.2 → 1.0.0-alpha.3

package/dist/index.d.ts

@@ -325,21 +325,6 @@ declare class LunoraError extends Error {
   constructor(code: LunoraErrorCode, message?: string);
 }
 /**
-* The per-table `ctx.db` accessor (the `ctx.db.messages.findMany(...)` form) and
-* the kitcn-style `ctx.orm` namespace, as plain runtime helpers. This is the ONE
-* source of truth for the facade shape, shared by two callers so they can never
-* drift (a drift here is security-relevant — a facade accessor the RLS
-* middleware forgot to re-bind would read around policy). `@lunora/codegen`
-* emits `ctx.db`/`ctx.orm` by calling these over the raw shard writer (and the
-* D1 `globalDb` writer for `.global()` tables); the RLS middleware re-binds the
-* policy tables by calling them over the policy-enforcing wrapped writer.
-*
-* `bindTableFacade(writer, table)` pins `tableName` on the structural writer so
-* callers address rows by id (`get`/`delete`/`patch`/`replace`) or by the bound
-* table (everything else). The binding is identical regardless of which writer
-* is passed — that's the whole point.
-*/
-/**
 * Minimal structural writer the facade binds over. Declared with **method**
 * syntax (not arrow properties) so a more-specifically-typed writer — both
 * `@lunora/do`'s `DatabaseWriterLike` and the RLS middleware's wrapped writer —
@@ -349,7 +334,9 @@ declare class LunoraError extends Error {
 interface FacadeWriterLike {
   aggregate(tableName: string, options: unknown): Promise<unknown>;
   count(tableName: string, where?: unknown): Promise<number>;
-  delete(id: string, expectedTable?: string): Promise<void>;
+  delete(id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }): Promise<void>;
   deleteMany?(ids: ReadonlyArray<string>, options?: {
     limit?: number;
   }, expectedTable?: string): Promise<{
@@ -377,6 +364,7 @@ interface FacadeWriterLike {
   rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
   rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
   replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  restore?(id: string, expectedTable?: string): Promise<void>;
 }
 /** The per-table accessor object returned for the `ctx.db` table form. */
 interface FacadeEntry {
@@ -388,12 +376,16 @@ interface FacadeEntry {
   }) => Promise<{
     deleted: number;
   }>;
+  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
+  exists: (where?: unknown) => Promise<boolean>;
   findFirst: (args?: unknown) => Promise<unknown>;
   findFirstOrThrow: (args?: unknown) => Promise<unknown>;
   findMany: (args?: unknown) => Promise<unknown>;
   get: (id: string) => Promise<unknown>;
   groupBy: (options: unknown) => Promise<unknown>;
-  insert: (document: Record<string, unknown>) => Promise<string>;
+  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
+  hardDelete: (id: string) => Promise<void>;
+  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
   insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
   }) => Promise<string[]>;
@@ -407,8 +399,47 @@ interface FacadeEntry {
   rank: (indexName: string, options: unknown) => Promise<unknown>;
   rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
   replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
+  restore: (id: string) => Promise<void>;
+  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
+  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
+  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
+  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
   withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
 }
+/** Options accepted by the per-table `insert` accessor. */
+interface FacadeInsertOptions {
+  /**
+  * When `true`, a UNIQUE-constraint breach is swallowed: the insert becomes a
+  * silent no-op and resolves to `null` instead of throwing a `CONFLICT`. Any
+  * other error still propagates. Mirrors better-drizzle's `create({ skipDuplicates })`.
+  */
+  skipDuplicates?: boolean;
+}
+/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
+type UpsertTarget = ReadonlyArray<string> | string;
+/** Argument to the per-table `upsert` accessor. */
+interface UpsertArgs {
+  /** Document inserted when no existing row matches the `target`. */
+  create: Record<string, unknown>;
+  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
+  target: UpsertTarget;
+  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
+  update?: Record<string, unknown>;
+}
+/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
+interface UpsertResult {
+  created: boolean;
+  id: string;
+}
+/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
+interface UpsertManyArgs {
+  rows: ReadonlyArray<{
+    create: Record<string, unknown>;
+    update?: Record<string, unknown>;
+  }>;
+  target: UpsertTarget;
+}
 /**
 * Bind a structural writer to one table, producing its `ctx.db` table accessor.
 *
@@ -426,7 +457,7 @@ declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) =>
 interface OrmLike {
   delete: (table: string, id: string) => Promise<void>;
   insert: (table: string) => {
-    values: (document: Record<string, unknown>) => Promise<string>;
+    values: (document: Record<string, unknown>) => Promise<null | string>;
   };
   query: Record<string, FacadeEntry>;
   replace: (table: string, id: string) => {
@@ -1168,6 +1199,22 @@ interface TableBuilder<Shape extends Record<string, Validator> = Record<string,
   }) => TableBuilder<Shape>;
   /** Route storage by the named field — one DO per distinct value. */
   shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+  * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
+  * default `deletedAt`) and changes `ctx.db.&lt;table>.delete()` to **set** it
+  * instead of removing the row; `onDelete: "cascade"` children are recursively
+  * soft-deleted too. **List reads** (`findMany`/`findFirst`/`query()`/`count`/
+  * `aggregate`/relation loads) then hide soft-deleted rows unless they pass
+  * `includeDeleted: true`; by-id `get`/`patch`/`replace` and the new
+  * `restore()` still address the row directly. `hardDelete()` physically
+  * removes it (cascading as a real delete). Note: `includeDeleted` is a read
+  * scope, not access control — anyone who can run the read can set it; a unique
+  * index still rejects a new row that collides with a soft-deleted one (the row
+  * physically persists).
+  */
+  softDelete: (options?: {
+    field?: string;
+  }) => TableBuilder<Shape>;
   /** Declare named lifecycle triggers fired inline within the write path. */
   triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
   /** Declare a vector index over a single text field on this table. */
@@ -1190,7 +1237,7 @@ interface VectorIndexOptions {
 * Build a table definition. Returned object is both the table definition (for
 * `defineSchema`) and a fluent builder for indexes + sharding metadata.
 */
-declare const defineTable: <Shape extends Record<string, Validator>>(shape: Shape) => TableBuilder<Shape>;
+declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
 /**
 * Declare a standalone vector index (DSL Shape B). Pass the returned value in
 * the `vectorIndexes` map of {@link defineSchema} when the source is derived
@@ -1562,7 +1609,9 @@ interface DatabaseWriterLike {
   */
   aggregate: (tableName: string, options: AggregateArgs) => Promise<null | number>;
   count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
-  delete: (id: string, expectedTable?: string) => Promise<void>;
+  delete: (id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }) => Promise<void>;
   deleteMany: (ids: ReadonlyArray<string>, options?: {
     limit?: number;
   }, expectedTable?: string) => Promise<{
@@ -1633,6 +1682,7 @@ interface DatabaseWriterLike {
   */
   rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage>;
   replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
 }
 /**
 * What a procedure's `ctx.db` must structurally satisfy for the middleware

package/dist/index.mjs

@@ -2,21 +2,21 @@ export { default as asBucketStorage } from './packem_shared/asBucketStorage-Cnxd
 export { initLunora } from './packem_shared/initLunora-CATvPsVt.mjs';
 export { LunoraEnvError, defineEnv, redactSecrets } from './packem_shared/LunoraEnvError-DjFkpkSP.mjs';
 export { LunoraError } from './packem_shared/LunoraError-DhggBJZF.mjs';
-export { bindOrm, bindTableFacade } from './packem_shared/bindOrm-DCuyr46L.mjs';
+export { bindOrm, bindTableFacade } from './packem_shared/bindOrm-Ce57S3N9.mjs';
 export { httpAction, httpRoute, httpRouter, serveStorageObject } from './packem_shared/httpAction-B7FYUEgr.mjs';
 export { onConnect, onDisconnect } from './packem_shared/onConnect-CIPXKPyw.mjs';
 export { defineMigration } from './packem_shared/defineMigration-CAJLr6fx.mjs';
 export { composePluginMiddleware, defineComponent, definePlugin, defineSchemaExtension, installPlugins, mergeSchemaExtension } from './packem_shared/composePluginMiddleware-Ck5_TUO8.mjs';
-export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-BZYd5-uo.mjs';
+export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-UQuUI5sV.mjs';
 export { protectPublic } from './packem_shared/protectPublic-BjFkQ_Or.mjs';
-export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-DxSso0rH.mjs';
+export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-B20MIOmj.mjs';
 export { anyApi } from './types.mjs';
 export { cronJobs } from '@lunora/scheduler';
 export { ValidationError, v } from '@lunora/values';
 export { createPolicyDsl, definePermission, definePolicies, definePolicy, defineRole } from './packem_shared/createPolicyDsl-De67zPDS.mjs';
 export { defineStorageRule, defineStorageRules } from './packem_shared/defineStorageRule-qu0mpilX.mjs';
-export { mask } from './packem_shared/mask-Jc84C_hK.mjs';
-export { rls } from './packem_shared/rls-BDKRbMCA.mjs';
+export { mask } from './packem_shared/mask-eCUYOwhd.mjs';
+export { rls } from './packem_shared/rls-Bi9HiyDC.mjs';
 export { storageRules } from './packem_shared/storageRules-4a30FSpI.mjs';
 
 const VERSION = "0.0.0";

package/dist/packem_shared/{PRESENCE_DEFAULT_TTL_MS-BZYd5-uo.mjs → PRESENCE_DEFAULT_TTL_MS-UQuUI5sV.mjs}

@@ -3,7 +3,7 @@ import { initLunora } from './initLunora-CATvPsVt.mjs';
 import { LunoraError } from './LunoraError-DhggBJZF.mjs';
 import { onDisconnect } from './onConnect-CIPXKPyw.mjs';
 import { defineSchemaExtension, defineComponent } from './composePluginMiddleware-Ck5_TUO8.mjs';
-import { defineTable } from './defineAggregateIndex-DxSso0rH.mjs';
+import { defineTable } from './defineAggregateIndex-B20MIOmj.mjs';
 
 const DEFAULT_TTL_MS = 3e4;
 const MAX_DATA_BYTES = 4096;

package/dist/packem_shared/{bindOrm-DCuyr46L.mjs → bindOrm-Ce57S3N9.mjs}

@@ -1,4 +1,42 @@
+const isUniqueConflict = (error) => typeof error === "object" && error !== null && error.code === "CONFLICT" && error.kind === "unique";
+const buildUpsertWhere = (tableName, target, create) => {
+  const fields = typeof target === "string" ? [target] : target;
+  if (fields.length === 0) {
+    throw new Error(`ctx.db.${tableName}.upsert: "target" must name at least one field`);
+  }
+  const where = {};
+  for (const field of fields) {
+    if (!(field in create)) {
+      throw new Error(`ctx.db.${tableName}.upsert: target field "${field}" is missing from the create document`);
+    }
+    where[field] = create[field];
+  }
+  return where;
+};
 const bindTableFacade = (writer, tableName) => {
+  const insert = async (document, options) => {
+    if (options?.skipDuplicates !== true) {
+      return writer.insert(tableName, document);
+    }
+    try {
+      return await writer.insert(tableName, document);
+    } catch (error) {
+      if (isUniqueConflict(error)) {
+        return null;
+      }
+      throw error;
+    }
+  };
+  const upsert = async ({ create, target, update }) => {
+    const where = buildUpsertWhere(tableName, target, create);
+    const existing = await writer.findFirst(tableName, { where });
+    if (existing && typeof existing["_id"] === "string") {
+      await writer.patch(existing["_id"], update ?? create, tableName);
+      return { created: false, id: existing["_id"] };
+    }
+    const id = await writer.insert(tableName, create);
+    return { created: true, id };
+  };
   return {
     aggregate: (options) => writer.aggregate(tableName, options),
     count: (where) => writer.count(tableName, where),
@@ -14,12 +52,17 @@ const bindTableFacade = (writer, tableName) => {
       }
       return writer.deleteMany(ids, options, tableName);
     },
+    // `exists` reuses `findFirst` (RLS-filtered, indexed when a `.withIndex`-able
+    // `where` is supplied) and only asks whether a row came back — no count scan.
+    exists: async (where) => await writer.findFirst(tableName, where === void 0 ? void 0 : { where }) !== null,
     findFirst: (args) => writer.findFirst(tableName, args),
     findFirstOrThrow: (args) => writer.findFirstOrThrow(tableName, args),
     findMany: (args) => writer.findMany(tableName, args),
     get: (id) => writer.get(id, tableName),
     groupBy: (options) => writer.groupBy(tableName, options),
-    insert: (document) => writer.insert(tableName, document),
+    // Physical removal — bypasses `.softDelete()`. RLS gates it as a delete.
+    hardDelete: (id) => writer.delete(id, tableName, { hard: true }),
+    insert,
     insertMany: (documents, options) => {
       if (writer.insertMany === void 0) {
         throw new Error(`ctx.db.${tableName}.insertMany is unavailable: this writer has no batch insert`);
@@ -42,6 +85,20 @@ const bindTableFacade = (writer, tableName) => {
     rank: (indexName, options) => writer.rank(tableName, indexName, options),
     rankPage: (indexName, options) => writer.rankPage(tableName, indexName, options),
     replace: (id, document) => writer.replace(id, document, tableName),
+    restore: async (id) => {
+      if (!writer.restore) {
+        throw new Error(`ctx.db.${tableName}.restore is unavailable: this writer has no restore (is the table .softDelete()?)`);
+      }
+      await writer.restore(id, tableName);
+    },
+    upsert,
+    upsertMany: async ({ rows, target }) => {
+      const results = [];
+      for (const row of rows) {
+        results.push(await upsert({ create: row.create, target, update: row.update }));
+      }
+      return results;
+    },
     withSearchIndex: (indexName, search) => writer.query(tableName).withSearchIndex(indexName, search)
   };
 };

package/dist/packem_shared/{defineAggregateIndex-DxSso0rH.mjs → defineAggregateIndex-B20MIOmj.mjs}

@@ -1,4 +1,4 @@
-import { isOrWrapsFromValidator } from '@lunora/values';
+import { isOrWrapsFromValidator, v } from '@lunora/values';
 import { mergeSchemaExtension } from './composePluginMiddleware-Ck5_TUO8.mjs';
 
 const relationBuilder = {
@@ -22,7 +22,8 @@ const createTriggerBuilder = () => {
     beforeUpdate: (handler) => makeTrigger("before", "update", handler)
   };
 };
-const defineTable = (shape) => {
+const defineTable = (inputShape) => {
+  const shape = { ...inputShape };
   for (const [columnName, validator] of Object.entries(shape)) {
     if (isOrWrapsFromValidator(validator)) {
       throw new Error(`defineTable: column "${columnName}" uses v.from() which is args-only — table columns need a concrete v.* type`);
@@ -39,6 +40,7 @@ const defineTable = (shape) => {
   let shardMode = { kind: "root" };
   let isExternallyManaged = false;
   let isPublic = false;
+  let softDelete;
   const builder = {
     aggregateIndex(name, options) {
       const op = options?.op ?? "count";
@@ -132,6 +134,17 @@ const defineTable = (shape) => {
     get shardMode() {
       return shardMode;
     },
+    get softDeleteMode() {
+      return softDelete;
+    },
+    softDelete(options) {
+      const field = options?.field ?? "deletedAt";
+      softDelete = { field };
+      if (!(field in shape)) {
+        shape[field] = v.optional(v.number().nullable());
+      }
+      return builder;
+    },
     get triggerMap() {
       return triggers;
     },

package/dist/packem_shared/{mask-Jc84C_hK.mjs → mask-eCUYOwhd.mjs}

@@ -1,5 +1,5 @@
 import { LunoraError } from './LunoraError-DhggBJZF.mjs';
-import { bindTableFacade, bindOrm } from './bindOrm-DCuyr46L.mjs';
+import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
 
 const permissionName = (permission) => typeof permission === "string" ? permission : permission.name;
 const indexRolePermissions = (roles) => {

package/dist/packem_shared/{rls-BDKRbMCA.mjs → rls-Bi9HiyDC.mjs}

@@ -1,5 +1,5 @@
 import { LunoraError } from './LunoraError-DhggBJZF.mjs';
-import { bindTableFacade, bindOrm } from './bindOrm-DCuyr46L.mjs';
+import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
 
 const DEFAULT_BATCH_LIMIT = 500;
 const assertBatchLimit = (count, limit, op) => {
@@ -324,7 +324,7 @@ const wrapDatabase = (base, raw, perTable, context) => {
         restrictsCounts: (args.restrictsCounts ?? false) || restricts
       });
     },
-    delete: (id, expectedTable) => gateById(id, "delete", (writer) => writer.delete(id, expectedTable), void 0, expectedTable),
+    delete: (id, expectedTable, options) => gateById(id, "delete", (writer) => writer.delete(id, expectedTable, options), void 0, expectedTable),
     async deleteMany(ids, options, expectedTable) {
       assertBatchLimit(ids.length, options?.limit, "deleteMany");
       for (const id of ids) {
@@ -441,6 +441,22 @@ const wrapDatabase = (base, raw, perTable, context) => {
       }
       return reader.filter((document) => matchesWhere(document, baseWhere));
     },
+    // Restore clears the soft-delete marker — a by-id un-delete, gated as an
+    // "update" (the policy that governs patch). No post-image check: the
+    // writer owns the marker field, so we only enforce the pre-image USING.
+    restore: (id, expectedTable) => gateById(
+      id,
+      "update",
+      async (writer) => {
+        const perform = writer.restore ?? raw.restore;
+        if (!perform) {
+          throw new LunoraError("BAD_REQUEST", "restore is not supported by this writer");
+        }
+        await perform(id, expectedTable);
+      },
+      void 0,
+      expectedTable
+    ),
     replace: (id, document, expectedTable) => gateById(
       id,
       "update",

package/dist/rls/testing.mjs

@@ -1,4 +1,4 @@
-import { indexRolePermissions, computeReadBaseWhere, matchesWhere, evaluateWrite, permissionName } from '../packem_shared/rls-BDKRbMCA.mjs';
+import { indexRolePermissions, computeReadBaseWhere, matchesWhere, evaluateWrite, permissionName } from '../packem_shared/rls-Bi9HiyDC.mjs';
 
 const expectPolicy = (policies, options = {}) => {
   const rolePermissions = indexRolePermissions(options.roles);

package/dist/types.d.mts

@@ -165,6 +165,20 @@ interface TableDefinition<Shape extends Record<string, Validator> = Record<strin
   shape: Shape;
   shardMode: ShardMode;
   /**
+  * Set by `.softDelete()` (named `softDeleteMode`, not `softDelete`, so the
+  * data field doesn't collide with the fluent `.softDelete()` builder method —
+  * same convention as `shardBy()`/`shardMode`). When present, the table carries
+  * a nullable timestamp column (`field`, default `deletedAt`):
+  * `ctx.db.&lt;table>.delete()` flips it instead of physically removing the row,
+  * and **list reads** (`findMany`/`findFirst`/`query()`/`count`/`aggregate`/
+  * relation loads) hide rows whose `field` is set unless
+  * `includeDeleted: true` is passed. By-id `get`/`patch`/`replace` and
+  * `restore` are unaffected. Absent ⇒ deletes are physical, as before.
+  */
+  softDeleteMode?: {
+    field: string;
+  };
+  /**
   * Declared lifecycle triggers keyed by accessor name; empty unless
   * `.triggers()` was called. Named `triggerMap` (not `triggers`) so the
   * fluent `.triggers((t) => …)` builder method doesn't collide with this

package/dist/types.d.ts

@@ -165,6 +165,20 @@ interface TableDefinition<Shape extends Record<string, Validator> = Record<strin
   shape: Shape;
   shardMode: ShardMode;
   /**
+  * Set by `.softDelete()` (named `softDeleteMode`, not `softDelete`, so the
+  * data field doesn't collide with the fluent `.softDelete()` builder method —
+  * same convention as `shardBy()`/`shardMode`). When present, the table carries
+  * a nullable timestamp column (`field`, default `deletedAt`):
+  * `ctx.db.&lt;table>.delete()` flips it instead of physically removing the row,
+  * and **list reads** (`findMany`/`findFirst`/`query()`/`count`/`aggregate`/
+  * relation loads) hide rows whose `field` is set unless
+  * `includeDeleted: true` is passed. By-id `get`/`patch`/`replace` and
+  * `restore` are unaffected. Absent ⇒ deletes are physical, as before.
+  */
+  softDeleteMode?: {
+    field: string;
+  };
+  /**
   * Declared lifecycle triggers keyed by accessor name; empty unless
   * `.triggers()` was called. Named `triggerMap` (not `triggers`) so the
   * fluent `.triggers((t) => …)` builder method doesn't collide with this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/server",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Server primitives for Lunora: defineSchema, defineTable, query, mutation, and action",
   "keywords": [
     "backend",
@@ -63,7 +63,7 @@
   },
   "dependencies": {
     "@lunora/scheduler": "1.0.0-alpha.1",
-    "@lunora/values": "1.0.0-alpha.1",
+    "@lunora/values": "1.0.0-alpha.2",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.26"
   },