@ibiliaze/stringman 3.14.0 → 3.15.0

package/dist/index.d.ts

@@ -154,6 +154,7 @@ export declare const ticket: {
         sectionId: string;
         row: number;
         col: number;
+        fixtureId?: string;
         rndLen?: number;
         dashed?: boolean;
     }) => string;

package/dist/seat.d.ts

@@ -11,5 +11,5 @@ export declare const getFromItemId: (itemId: string) => {
     fixtureId: string;
     sectionId: string;
     seatId: string;
-    categoryId: String;
+    categoryId: string;
 };

package/dist/ticket.d.ts

@@ -1,30 +1,90 @@
+/**
+ * Compute a Luhn mod-10 check digit for a numeric string.
+ * @param digits Numeric string (no separators).
+ * @returns Single check digit as a string.
+ */
 export declare const luhn10: (digits: string) => string;
+/**
+ * Compact, stable 2-digit number for a venue or any short code.
+ * Uses a small SHA-1 based hash and modulo to fit the requested width.
+ */
 export declare const venueBlockNum: (venueCode: string, len?: number) => string;
+/**
+ * Compact, stable 2-digit number for a Fixture/Match ID string.
+ * If you pass your DB fixtureId here, you’ll get a short numeric block.
+ */
+export declare const fixtureIdBlockNum: (fixtureId: string, len?: number) => string;
+/**
+ * Compact, stable 3-digit number for a specific seat (section + row + col).
+ */
 export declare const seatBlockNum: (sectionId: string, row: number, col: number, len?: number) => string;
+/**
+ * 6-digit date/time block derived from local start time.
+ * Input format expected: "YYYY-MM-DDThh:mm" (local, no 'Z').
+ * Encodes YYMMDDhhmm then reduces modulo 10^len to keep width stable.
+ */
 export declare const fixtureBlockNum: (fixtureLocalIso: string, len?: number) => string;
+/**
+ * Cryptographically strong random numeric block of the given length.
+ */
 export declare const rndBlockNum: (len?: number) => string;
+/**
+ * Build a numeric ticket code with blocks ordered to match the picture *in reverse*:
+ *   Random (3) + Sector/Block/Col (3) + Date/Time (6) + Fixture/Match ID (2) + Luhn(1)
+ *
+ * Default dashed display groups: 3-3-6-2-1
+ *
+ * Lengths are chosen to keep the overall size at 15 digits (incl. Luhn),
+ * which plays nicely with scanners and manual entry.
+ */
 export declare const buildTicketCodeNumeric: (args: {
+    /** Human/ops venue short code (e.g. "SB"). Used only if fixtureId is not provided. */
     venueCode: string;
+    /** Local fixture start time, "YYYY-MM-DDThh:mm" (no 'Z'). */
     fixtureLocalIso: string;
+    /** Section identifier as used in your DB. */
     sectionId: string;
+    /** Seat row number. */
     row: number;
+    /** Seat column/number. */
     col: number;
+    /** Optional: your DB fixtureId. If present, becomes the 2-digit “Fixture/Match ID” block. */
+    fixtureId?: string;
+    /** Random block length (default 3). */
     rndLen?: number;
+    /** Show dashes for readability (default true). */
     dashed?: boolean;
 }) => string;
+/**
+ * Validate a code built by buildTicketCodeNumeric (dashes optional).
+ * Checks: numeric, correct total length (15), and Luhn checksum.
+ */
 export declare const validateTicketCodeNumeric: (code: string) => boolean;
+/**
+ * A stable, human-readable internal ID for a seat within a fixture.
+ * (Not used in the printed/scanned code — just handy elsewhere.)
+ */
 export declare const getTicketId: ({ fixtureId, sectionName, seatName, }: {
     fixtureId: string;
     sectionName: string;
     seatName: string;
 }) => string;
 export declare const buildTicketCode: (args: {
+    /** Human/ops venue short code (e.g. "SB"). Used only if fixtureId is not provided. */
     venueCode: string;
+    /** Local fixture start time, "YYYY-MM-DDThh:mm" (no 'Z'). */
     fixtureLocalIso: string;
+    /** Section identifier as used in your DB. */
     sectionId: string;
+    /** Seat row number. */
     row: number;
+    /** Seat column/number. */
     col: number;
+    /** Optional: your DB fixtureId. If present, becomes the 2-digit “Fixture/Match ID” block. */
+    fixtureId?: string;
+    /** Random block length (default 3). */
     rndLen?: number;
+    /** Show dashes for readability (default true). */
     dashed?: boolean;
 }) => string;
 export declare const validateTicketCode: (code: string) => boolean;

package/dist/ticket.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateTicketCode = exports.buildTicketCode = exports.getTicketId = exports.validateTicketCodeNumeric = exports.buildTicketCodeNumeric = exports.rndBlockNum = exports.fixtureBlockNum = exports.seatBlockNum = exports.venueBlockNum = exports.luhn10 = void 0;
+exports.validateTicketCode = exports.buildTicketCode = exports.getTicketId = exports.validateTicketCodeNumeric = exports.buildTicketCodeNumeric = exports.rndBlockNum = exports.fixtureBlockNum = exports.seatBlockNum = exports.fixtureIdBlockNum = exports.venueBlockNum = exports.luhn10 = void 0;
 const node_crypto_1 = require("node:crypto");
-// ---------- helpers ----------
+/**
+ * Left-pad a positive integer with zeros to a fixed width.
+ */
 const pad = (n, len) => n.toString().padStart(len, '0');
-// Luhn mod-10 for digits
+/**
+ * Compute a Luhn mod-10 check digit for a numeric string.
+ * @param digits Numeric string (no separators).
+ * @returns Single check digit as a string.
+ */
 const luhn10 = (digits) => {
     let sum = 0;
     let dbl = false;
@@ -22,11 +28,13 @@ const luhn10 = (digits) => {
     return String(check);
 };
 exports.luhn10 = luhn10;
-// ---------- numeric blocks ----------
+/**
+ * Compact, stable 2-digit number for a venue or any short code.
+ * Uses a small SHA-1 based hash and modulo to fit the requested width.
+ */
 const venueBlockNum = (venueCode, len = 2) => {
     try {
-        // Small, stable hash of the code -> 0..(10^len - 1)
-        const h = (0, node_crypto_1.createHash)('sha1').update(venueCode.toUpperCase()).digest(); // 20 bytes
+        const h = (0, node_crypto_1.createHash)('sha1').update(venueCode.toUpperCase()).digest();
         const n = ((h[0] << 8) | h[1]) % 10 ** len;
         return pad(n, len);
     }
@@ -35,9 +43,26 @@ const venueBlockNum = (venueCode, len = 2) => {
     }
 };
 exports.venueBlockNum = venueBlockNum;
+/**
+ * Compact, stable 2-digit number for a Fixture/Match ID string.
+ * If you pass your DB fixtureId here, you’ll get a short numeric block.
+ */
+const fixtureIdBlockNum = (fixtureId, len = 2) => {
+    try {
+        const h = (0, node_crypto_1.createHash)('sha1').update(fixtureId).digest();
+        const n = ((h[0] << 8) | h[1]) % 10 ** len;
+        return pad(n, len);
+    }
+    catch {
+        return ''.padStart(len, '0');
+    }
+};
+exports.fixtureIdBlockNum = fixtureIdBlockNum;
+/**
+ * Compact, stable 3-digit number for a specific seat (section + row + col).
+ */
 const seatBlockNum = (sectionId, row, col, len = 3) => {
     try {
-        // Hash -> 16-bit -> modulo 10^len
         const h = (0, node_crypto_1.createHash)('sha1').update(`${sectionId}:${row}:${col}`).digest();
         const n16 = (h[0] << 8) | h[1];
         const n = n16 % 10 ** len;
@@ -48,14 +73,17 @@ const seatBlockNum = (sectionId, row, col, len = 3) => {
     }
 };
 exports.seatBlockNum = seatBlockNum;
+/**
+ * 6-digit date/time block derived from local start time.
+ * Input format expected: "YYYY-MM-DDThh:mm" (local, no 'Z').
+ * Encodes YYMMDDhhmm then reduces modulo 10^len to keep width stable.
+ */
 const fixtureBlockNum = (fixtureLocalIso, len = 6) => {
     try {
-        // Expect "YYYY-MM-DDThh:mm" (local, no Z).
         const m = fixtureLocalIso.match(/^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})/);
         if (!m)
             throw new Error('Bad fixtureLocalIso');
         const [_, y, M, d, h, mnt] = m;
-        // YYMMDDhhmm is 10 digits; compress to len digits via mod 10^len.
         const compact = Number(`${y.slice(2)}${M}${d}${h}${mnt}`); // e.g. 2510312000
         const n = compact % 10 ** len;
         return pad(n, len);
@@ -65,9 +93,11 @@ const fixtureBlockNum = (fixtureLocalIso, len = 6) => {
     }
 };
 exports.fixtureBlockNum = fixtureBlockNum;
+/**
+ * Cryptographically strong random numeric block of the given length.
+ */
 const rndBlockNum = (len = 3) => {
     try {
-        // Uniform cryptographic integer in [0, 10^len)
         const max = 10 ** len;
         return pad((0, node_crypto_1.randomInt)(0, max), len);
     }
@@ -76,31 +106,46 @@ const rndBlockNum = (len = 3) => {
     }
 };
 exports.rndBlockNum = rndBlockNum;
-// ---------- builder & validator (numeric-only) ----------
+/**
+ * Build a numeric ticket code with blocks ordered to match the picture *in reverse*:
+ *   Random (3) + Sector/Block/Col (3) + Date/Time (6) + Fixture/Match ID (2) + Luhn(1)
+ *
+ * Default dashed display groups: 3-3-6-2-1
+ *
+ * Lengths are chosen to keep the overall size at 15 digits (incl. Luhn),
+ * which plays nicely with scanners and manual entry.
+ */
 const buildTicketCodeNumeric = (args) => {
     try {
-        const VV = (0, exports.venueBlockNum)(args.venueCode, 2); // 2 digits
-        const E = (0, exports.fixtureBlockNum)(args.fixtureLocalIso, 6); // 6 digits
-        const S = (0, exports.seatBlockNum)(args.sectionId, args.row, args.col); // 3 digits
-        const R = (0, exports.rndBlockNum)(args.rndLen ?? 3); // 3 digits
-        const body = `${VV}${E}${S}${R}`; // 14 digits
+        // --- individual blocks ---
+        const R = (0, exports.rndBlockNum)(args.rndLen ?? 3); // Random (3)
+        const S = (0, exports.seatBlockNum)(args.sectionId, args.row, args.col); // Seat (3)
+        const D = (0, exports.fixtureBlockNum)(args.fixtureLocalIso, 6); // Date/Time (6)
+        // Fixture/Match ID (2): prefer fixtureId; fallback to venue code hash
+        const F = args.fixtureId ? (0, exports.fixtureIdBlockNum)(args.fixtureId, 2) : (0, exports.venueBlockNum)(args.venueCode, 2);
+        // --- assemble (REVERSED order vs the picture’s left-to-right) ---
+        const body = `${R}${S}${D}${F}`; // 3+3+6+2 = 14
         const C = (0, exports.luhn10)(body); // 1 digit
-        const numeric = `${body}${C}`; // 15 digits total
+        const numeric = `${body}${C}`; // total 15 digits
         if (args.dashed === false)
             return numeric;
-        // Grouping 2-6-3-3-1 for readability
-        return `${VV}-${E}-${S}-${R}-${C}`;
+        // Readability grouping for scanners/ushers: 3-3-6-2-1
+        return `${R}-${S}-${D}-${F}-${C}`;
     }
     catch {
         return '';
     }
 };
 exports.buildTicketCodeNumeric = buildTicketCodeNumeric;
+/**
+ * Validate a code built by buildTicketCodeNumeric (dashes optional).
+ * Checks: numeric, correct total length (15), and Luhn checksum.
+ */
 const validateTicketCodeNumeric = (code) => {
     try {
         const clean = code.replace(/-/g, '');
         if (!/^\d{15}$/.test(clean))
-            return false; // 2+6+3+3+1
+            return false; // 3+3+6+2+1
         const body = clean.slice(0, -1);
         const check = clean.slice(-1);
         return (0, exports.luhn10)(body) === check;
@@ -110,8 +155,12 @@ const validateTicketCodeNumeric = (code) => {
     }
 };
 exports.validateTicketCodeNumeric = validateTicketCodeNumeric;
+/**
+ * A stable, human-readable internal ID for a seat within a fixture.
+ * (Not used in the printed/scanned code — just handy elsewhere.)
+ */
 const getTicketId = ({ fixtureId, sectionName, seatName, }) => `${sectionName}-${seatName}-${fixtureId}`;
 exports.getTicketId = getTicketId;
-// ---------- compatibility shim (if you want same names as before) ----------
+// Compatibility aliases (if other code imports these names already)
 exports.buildTicketCode = exports.buildTicketCodeNumeric;
 exports.validateTicketCode = exports.validateTicketCodeNumeric;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ibiliaze/stringman",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "pub": "npm publish --access public",
-    "git": "git add .; git commit -m 'changes'; git tag -a v3.14.0 -m 'v3.14.0'; git push origin v3.14.0; git push",
+    "git": "git add .; git commit -m 'changes'; git tag -a v3.14.1 -m 'v3.14.1'; git push origin v3.14.1; git push",
     "push": "npm run build; npm run git; npm run pub"
   },
   "author": "Ibi Hasanli",

package/src/seat.ts

@@ -17,4 +17,4 @@ export const getItemId = ({
 
 export const getFromItemId = (
   itemId: string
-): { fixtureId: string; sectionId: string; seatId: string; categoryId: String } => JSON.parse(itemId);
+): { fixtureId: string; sectionId: string; seatId: string; categoryId: string } => JSON.parse(itemId);

package/src/ticket.ts

@@ -1,9 +1,15 @@
 import { createHash, randomInt } from 'node:crypto';
 
-// ---------- helpers ----------
+/**
+ * Left-pad a positive integer with zeros to a fixed width.
+ */
 const pad = (n: number, len: number) => n.toString().padStart(len, '0');
 
-// Luhn mod-10 for digits
+/**
+ * Compute a Luhn mod-10 check digit for a numeric string.
+ * @param digits Numeric string (no separators).
+ * @returns Single check digit as a string.
+ */
 export const luhn10 = (digits: string): string => {
   let sum = 0;
   let dbl = false;
@@ -20,11 +26,13 @@ export const luhn10 = (digits: string): string => {
   return String(check);
 };
 
-// ---------- numeric blocks ----------
+/**
+ * Compact, stable 2-digit number for a venue or any short code.
+ * Uses a small SHA-1 based hash and modulo to fit the requested width.
+ */
 export const venueBlockNum = (venueCode: string, len = 2) => {
   try {
-    // Small, stable hash of the code -> 0..(10^len - 1)
-    const h = createHash('sha1').update(venueCode.toUpperCase()).digest(); // 20 bytes
+    const h = createHash('sha1').update(venueCode.toUpperCase()).digest();
     const n = ((h[0] << 8) | h[1]) % 10 ** len;
     return pad(n, len);
   } catch {
@@ -32,9 +40,25 @@ export const venueBlockNum = (venueCode: string, len = 2) => {
   }
 };
 
+/**
+ * Compact, stable 2-digit number for a Fixture/Match ID string.
+ * If you pass your DB fixtureId here, you’ll get a short numeric block.
+ */
+export const fixtureIdBlockNum = (fixtureId: string, len = 2) => {
+  try {
+    const h = createHash('sha1').update(fixtureId).digest();
+    const n = ((h[0] << 8) | h[1]) % 10 ** len;
+    return pad(n, len);
+  } catch {
+    return ''.padStart(len, '0');
+  }
+};
+
+/**
+ * Compact, stable 3-digit number for a specific seat (section + row + col).
+ */
 export const seatBlockNum = (sectionId: string, row: number, col: number, len = 3) => {
   try {
-    // Hash -> 16-bit -> modulo 10^len
     const h = createHash('sha1').update(`${sectionId}:${row}:${col}`).digest();
     const n16 = (h[0] << 8) | h[1];
     const n = n16 % 10 ** len;
@@ -44,13 +68,16 @@ export const seatBlockNum = (sectionId: string, row: number, col: number, len =
   }
 };
 
+/**
+ * 6-digit date/time block derived from local start time.
+ * Input format expected: "YYYY-MM-DDThh:mm" (local, no 'Z').
+ * Encodes YYMMDDhhmm then reduces modulo 10^len to keep width stable.
+ */
 export const fixtureBlockNum = (fixtureLocalIso: string, len = 6) => {
   try {
-    // Expect "YYYY-MM-DDThh:mm" (local, no Z).
     const m = fixtureLocalIso.match(/^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})/);
     if (!m) throw new Error('Bad fixtureLocalIso');
     const [_, y, M, d, h, mnt] = m;
-    // YYMMDDhhmm is 10 digits; compress to len digits via mod 10^len.
     const compact = Number(`${y.slice(2)}${M}${d}${h}${mnt}`); // e.g. 2510312000
     const n = compact % 10 ** len;
     return pad(n, len);
@@ -59,9 +86,11 @@ export const fixtureBlockNum = (fixtureLocalIso: string, len = 6) => {
   }
 };
 
+/**
+ * Cryptographically strong random numeric block of the given length.
+ */
 export const rndBlockNum = (len = 3) => {
   try {
-    // Uniform cryptographic integer in [0, 10^len)
     const max = 10 ** len;
     return pad(randomInt(0, max), len);
   } catch {
@@ -69,38 +98,63 @@ export const rndBlockNum = (len = 3) => {
   }
 };
 
-// ---------- builder & validator (numeric-only) ----------
+/**
+ * Build a numeric ticket code with blocks ordered to match the picture *in reverse*:
+ *   Random (3) + Sector/Block/Col (3) + Date/Time (6) + Fixture/Match ID (2) + Luhn(1)
+ *
+ * Default dashed display groups: 3-3-6-2-1
+ *
+ * Lengths are chosen to keep the overall size at 15 digits (incl. Luhn),
+ * which plays nicely with scanners and manual entry.
+ */
 export const buildTicketCodeNumeric = (args: {
-  venueCode: string; // e.g. "SB"
-  fixtureLocalIso: string; // "2025-10-31T20:00" in venue TZ
+  /** Human/ops venue short code (e.g. "SB"). Used only if fixtureId is not provided. */
+  venueCode: string;
+  /** Local fixture start time, "YYYY-MM-DDThh:mm" (no 'Z'). */
+  fixtureLocalIso: string;
+  /** Section identifier as used in your DB. */
   sectionId: string;
+  /** Seat row number. */
   row: number;
+  /** Seat column/number. */
   col: number;
-  rndLen?: number; // default 3 (use 4 if you want more entropy)
-  dashed?: boolean; // default true (format with dashes)
+  /** Optional: your DB fixtureId. If present, becomes the 2-digit “Fixture/Match ID” block. */
+  fixtureId?: string;
+  /** Random block length (default 3). */
+  rndLen?: number;
+  /** Show dashes for readability (default true). */
+  dashed?: boolean;
 }) => {
   try {
-    const VV = venueBlockNum(args.venueCode, 2); // 2 digits
-    const E = fixtureBlockNum(args.fixtureLocalIso, 6); // 6 digits
-    const S = seatBlockNum(args.sectionId, args.row, args.col); // 3 digits
-    const R = rndBlockNum(args.rndLen ?? 3); // 3 digits
+    // --- individual blocks ---
+    const R = rndBlockNum(args.rndLen ?? 3); // Random (3)
+    const S = seatBlockNum(args.sectionId, args.row, args.col); // Seat (3)
+    const D = fixtureBlockNum(args.fixtureLocalIso, 6); // Date/Time (6)
+    // Fixture/Match ID (2): prefer fixtureId; fallback to venue code hash
+    const F = args.fixtureId ? fixtureIdBlockNum(args.fixtureId, 2) : venueBlockNum(args.venueCode, 2);
 
-    const body = `${VV}${E}${S}${R}`; // 14 digits
+    // --- assemble (REVERSED order vs the picture’s left-to-right) ---
+    const body = `${R}${S}${D}${F}`; // 3+3+6+2 = 14
     const C = luhn10(body); // 1 digit
-    const numeric = `${body}${C}`; // 15 digits total
+    const numeric = `${body}${C}`; // total 15 digits
 
     if (args.dashed === false) return numeric;
-    // Grouping 2-6-3-3-1 for readability
-    return `${VV}-${E}-${S}-${R}-${C}`;
+
+    // Readability grouping for scanners/ushers: 3-3-6-2-1
+    return `${R}-${S}-${D}-${F}-${C}`;
   } catch {
     return '';
   }
 };
 
+/**
+ * Validate a code built by buildTicketCodeNumeric (dashes optional).
+ * Checks: numeric, correct total length (15), and Luhn checksum.
+ */
 export const validateTicketCodeNumeric = (code: string) => {
   try {
     const clean = code.replace(/-/g, '');
-    if (!/^\d{15}$/.test(clean)) return false; // 2+6+3+3+1
+    if (!/^\d{15}$/.test(clean)) return false; // 3+3+6+2+1
     const body = clean.slice(0, -1);
     const check = clean.slice(-1);
     return luhn10(body) === check;
@@ -109,6 +163,10 @@ export const validateTicketCodeNumeric = (code: string) => {
   }
 };
 
+/**
+ * A stable, human-readable internal ID for a seat within a fixture.
+ * (Not used in the printed/scanned code — just handy elsewhere.)
+ */
 export const getTicketId = ({
   fixtureId,
   sectionName,
@@ -119,6 +177,6 @@ export const getTicketId = ({
   seatName: string;
 }) => `${sectionName}-${seatName}-${fixtureId}`;
 
-// ---------- compatibility shim (if you want same names as before) ----------
+// Compatibility aliases (if other code imports these names already)
 export const buildTicketCode = buildTicketCodeNumeric;
 export const validateTicketCode = validateTicketCodeNumeric;