nucleus-core-ts 0.10.113 → 0.10.115

package/dist/src/Client/ApiCaller/server.d.ts

@@ -35,6 +35,15 @@ export declare function serverRequestId(response: {
  * `requiresCaptcha` one the control-flag list above exists for.
  */
 export declare function normalizeResponseShape(response: unknown): unknown;
+/**
+ * Rewrite a `cookie` request header so it carries the values the backend just
+ * issued.
+ *
+ * The retry has to send the NEW access token. Headers here are built from the
+ * INCOMING request, so without this the second attempt re-sends the same expired
+ * token and earns the same 401 — a refresh that changes nothing.
+ */
+export declare function mergeCookieHeader(existing: string | undefined, setCookies: string[]): string;
 export declare function createServerFactory<TEndpoints extends Record<string, EndpointDefinition>>(endpoints: TEndpoints, config: ServerFactoryConfig, getCookies: () => Promise<CookieStore>, getHeaders: () => Promise<HeadersStore>): <K extends keyof TEndpoints & string>(endpointKey: K, payload: TEndpoints[K]["_payload"]) => Promise<ApiResponse<TEndpoints[K]["_success"], TEndpoints[K]["_error"]>>;
 export type ServerFactory<TEndpoints extends Record<string, EndpointDefinition>> = ReturnType<typeof createServerFactory<TEndpoints>>;
 /**

package/dist/src/Client/ApiCaller/types.d.ts

@@ -2472,6 +2472,24 @@ export interface ServerFactoryConfig {
         sessionToken?: string;
     };
     debug?: boolean;
+    /**
+     * What to do when the backend answers 401 because the access token has aged
+     * out. Without this the caller simply sees the 401 and the person is bounced
+     * to the login screen mid-task — on a thirty-minute token, every thirty
+     * minutes, no matter how recently they typed their password.
+     */
+    refresh?: {
+        /** Default: true. */
+        enabled?: boolean;
+        /** Where to ask. Default: `/auth/refresh`. */
+        endpoint?: string;
+        /**
+         * Paths that must never trigger a refresh, because a 401 from them IS the
+         * answer. Matched as substrings of the endpoint path. Defaults to the
+         * login, logout, register and refresh routes themselves.
+         */
+        excludePaths?: string[];
+    };
 }
 export interface ClientHookConfig<TEndpoints extends Record<string, EndpointDefinition>> {
     endpoints: TEndpoints;

package/dist/src/Nucleus/routes/entity/sortCollation.d.ts

@@ -0,0 +1,16 @@
+import { type SQL } from 'drizzle-orm';
+export declare const COLLATABLE_COLUMN_TYPES: Set<string>;
+/**
+ * A collation name is an IDENTIFIER, so it is interpolated into the SQL text
+ * and cannot be sent as a bound parameter. It comes from config rather than
+ * from a request, but "not attacker-controlled today" is not the same as safe:
+ * accept a bare identifier and nothing else.
+ */
+export declare function normalizeSortCollation(raw: unknown): string;
+/** True when `raw` was given but is not usable — the caller should log it. */
+export declare function isRejectedSortCollation(raw: unknown): boolean;
+/**
+ * Wraps a sort column in the configured collation when — and only when — the
+ * column is a character type.
+ */
+export declare function collateColumn(col: unknown, collation: string): SQL;

package/dist/src/Nucleus/routes/entity/types.d.ts

@@ -30,6 +30,8 @@ export interface EntityRouteConfig {
     entities: NucleusTable[];
     logger: Logger;
     databaseUrl?: string;
+    /** ICU collation for text-column sorts (see `database.sortCollation`). */
+    sortCollation?: string;
     dbPool?: import('pg').Pool | null;
     storage?: {
         enabled?: boolean;

package/dist/src/types.d.ts

@@ -26,6 +26,15 @@ export interface NucleusColumnValidation {
     customMessage?: string;
 }
 export type NucleusSanitizeOption = 'trim' | 'lowercase' | 'uppercase' | 'escapeHtml' | 'stripTags' | 'normalizeEmail' | 'toNumber' | 'toBoolean' | 'slugify';
+export interface NucleusColumnIdentity {
+    /** First value the sequence hands out. Set it above the largest number already stored. */
+    startWith?: number;
+    increment?: number;
+    minValue?: number;
+    maxValue?: number;
+    cache?: number;
+    cycle?: boolean;
+}
 export interface NucleusColumn {
     name: string;
     type: NucleusColumnType;
@@ -49,6 +58,12 @@ export interface NucleusColumn {
     generatedAlwaysAs?: string;
     generatedAlwaysAsIdentity?: boolean;
     generatedByDefaultAsIdentity?: boolean;
+    /**
+     * Where an identity column's numbering starts and how it steps. Needed when a
+     * column adopts identity over a table that already has rows: the sequence
+     * would otherwise restart at 1 and hand out numbers those rows already carry.
+     */
+    identity?: NucleusColumnIdentity;
     check?: string;
     comment?: string;
     validation?: NucleusColumnValidation;
@@ -210,6 +225,24 @@ export interface NucleusConfigOptions {
             maxUses?: number;
         };
         isMultiTenant?: boolean;
+        /**
+         * Collation applied to text-column sorts, e.g. `tr-TR-x-icu`.
+         *
+         * Postgres' default collation on a `C`/`POSIX` database orders by BYTE, so
+         * an "A-Z" list is not alphabetical in any language with letters outside
+         * ASCII. Measured on a Turkish catalogue: `ALBITROL` sorted before
+         * `Airtide` (uppercase letters sort before lowercase), and every name
+         * starting with ç/ğ/ı/ö/ş/ü landed after `z`. The list looked sorted and
+         * was not — the worst kind of wrong, because nothing about it invites a
+         * second look.
+         *
+         * Set the ICU collation for the install's language (`tr-TR-x-icu`,
+         * `de-DE-x-icu`, ...) and every entity sort on a text column uses it.
+         * Unset (default) keeps the database's own collation, so existing installs
+         * do not change order under them. An unknown collation is refused at boot
+         * rather than applied — see the entity route.
+         */
+        sortCollation?: string;
         schemas?: string[];
         /**
          * Deadline for the startup schema push (default 120000 ms).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleus-core-ts",
-  "version": "0.10.113",
+  "version": "0.10.115",
   "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
   "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
   "license": "SEE LICENSE IN LICENSE",

package/scripts/generate-schema.test.ts

@@ -273,3 +273,79 @@ describe('generateRelationsFile', () => {
     expect(code).toContain('surveys: one(surveys')
   })
 })
+
+/**
+ * Postgres starts a new identity sequence at 1.
+ *
+ * On an empty table that is correct. On a table that already holds rows it
+ * hands the next insert a number those rows already carry — and identity adds
+ * no unique index, so nothing objects. Biltim's `five_s_findings` is the case:
+ * `finding_no` is NOT NULL with no default, nothing in the app has ever
+ * assigned it, and every attempt to record a finding was refused with
+ * "finding_no is required". Giving the column identity fixes the refusal, and
+ * would then have produced a second finding numbered 1 sitting beside the
+ * first, in a register whose Excel export orders by that number.
+ */
+describe('an identity column can say where its numbering resumes', () => {
+  const emit = (col: Record<string, unknown>) => generateColumnCode(col as never, [], 'findings')
+
+  it('still emits a bare identity when nothing is asked for', () => {
+    // The existing behaviour, unchanged: adding the option must not alter what
+    // every column that does not use it generates.
+    expect(emit({ name: 'finding_no', type: 'integer', generatedByDefaultAsIdentity: true })).toBe(
+      "integer('finding_no').generatedByDefaultAsIdentity()"
+    )
+  })
+
+  it('carries the starting value through to Drizzle', () => {
+    expect(
+      emit({
+        name: 'finding_no',
+        type: 'integer',
+        generatedByDefaultAsIdentity: true,
+        identity: { startWith: 3 },
+      })
+    ).toContain('.generatedByDefaultAsIdentity({ startWith: 3 })')
+  })
+
+  it('carries the rest of the sequence options', () => {
+    const code = emit({
+      name: 'ticket_no',
+      type: 'integer',
+      generatedAlwaysAsIdentity: true,
+      identity: { startWith: 1000, increment: 10, minValue: 1, maxValue: 999999, cache: 5 },
+    })
+
+    expect(code).toContain('startWith: 1000')
+    expect(code).toContain('increment: 10')
+    expect(code).toContain('minValue: 1')
+    expect(code).toContain('maxValue: 999999')
+    expect(code).toContain('cache: 5')
+  })
+
+  it('an identity column still does not repeat notNull', () => {
+    // Identity implies NOT NULL; emitting both produced a schema Drizzle
+    // rejected. The option must not reopen that.
+    const code = emit({
+      name: 'finding_no',
+      type: 'integer',
+      notNull: true,
+      generatedByDefaultAsIdentity: true,
+      identity: { startWith: 3 },
+    })
+
+    expect(code).not.toContain('.notNull()')
+  })
+
+  it('still applies a unique index when one is declared', () => {
+    const code = emit({
+      name: 'finding_no',
+      type: 'integer',
+      generatedByDefaultAsIdentity: true,
+      unique: true,
+      identity: { startWith: 3 },
+    })
+
+    expect(code).toContain('.unique()')
+  })
+})

package/scripts/generate-schema.ts

@@ -33,6 +33,14 @@ interface Column {
   generatedAlwaysAs?: string
   generatedByDefaultAsIdentity?: boolean
   generatedAlwaysAsIdentity?: boolean
+  identity?: {
+    startWith?: number
+    increment?: number
+    minValue?: number
+    maxValue?: number
+    cache?: number
+    cycle?: boolean
+  }
   comment?: string
   check?: string
   sensitive?: boolean
@@ -228,6 +236,30 @@ export function selectEmittedTables<T extends { table_name: string }>(
   )
 }
 
+/**
+ * Identity sequence options, rendered for Drizzle.
+ *
+ * Postgres starts a new identity sequence at 1. On an empty table that is
+ * right; on a table that already holds rows it is not, and nothing says so —
+ * the next insert is handed 1 again and sits alongside the row that already
+ * carries it. Without a unique index (identity does not add one) there is no
+ * error, just two records wearing the same number and a report that orders by
+ * it. So a column adopting identity over existing data has to be able to say
+ * where the numbering resumes.
+ */
+function identityOptions(col: Column): string {
+  const id = col.identity
+  if (!id) return ''
+  const parts: string[] = []
+  if (id.startWith !== undefined) parts.push(`startWith: ${id.startWith}`)
+  if (id.increment !== undefined) parts.push(`increment: ${id.increment}`)
+  if (id.minValue !== undefined) parts.push(`minValue: ${id.minValue}`)
+  if (id.maxValue !== undefined) parts.push(`maxValue: ${id.maxValue}`)
+  if (id.cache !== undefined) parts.push(`cache: ${id.cache}`)
+  if (id.cycle !== undefined) parts.push(`cycle: ${id.cycle}`)
+  return parts.length ? `{ ${parts.join(', ')} }` : ''
+}
+
 export function generateColumnCode(
   col: Column,
   allTables: string[],
@@ -260,12 +292,12 @@ export function generateColumnCode(
   if (col.primaryKey) code += '.primaryKey()'
 
   if (col.generatedByDefaultAsIdentity) {
-    code += '.generatedByDefaultAsIdentity()'
+    code += `.generatedByDefaultAsIdentity(${identityOptions(col)})`
     if (col.unique) code += '.unique()'
     return code
   }
   if (col.generatedAlwaysAsIdentity) {
-    code += '.generatedAlwaysAsIdentity()'
+    code += `.generatedAlwaysAsIdentity(${identityOptions(col)})`
     if (col.unique) code += '.unique()'
     return code
   }