@zenuinebit/invoice-number 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZenuineBit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @zenuinebit/invoice-number
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sequential invoice numbers that restart each financial year, plus a check for the Indian GST format rule. No dependencies. Dates are `"YYYY-MM-DD"` strings.
+
+```ts
+import { next, checkGstFormat, financialYear } from "@zenuinebit/invoice-number";
+
+const format = { pattern: "INV/{FY}/{SEQ:4}" };       // reset defaults to "financial-year"
+
+// First invoice: no counter yet
+let r = next(null, "2025-04-01", format);              // { number: "INV/2025-26/0001", counter: { period: "2025-26", seq: 1 } }
+r = next(r.counter, "2025-09-10", format);             // "INV/2025-26/0002"
+r = next(r.counter, "2026-04-01", format);             // "INV/2026-27/0001" - new financial year
+
+checkGstFormat("INV/2025-26/0042");                    // { valid: true, problems: [] }
+financialYear("2025-03-31");                           // "2024-25"
+```
+
+**Pattern tokens:** `{FY}` 2025-26, `{FY2}` 2526, `{YYYY}`, `{YY}`, `{MM}`, `{SEQ:n}` (sequence padded to n digits) and `{SEQ}`.
+**Reset:** `"financial-year"` (default), `"calendar-year"`, `"month"`, `"never"`. `fyStartMonth` defaults to 4 (April).
+
+**Use it safely**
+- The package keeps no state. Store the counter in your database and call `next` inside the same transaction (or with a row lock) that saves the invoice. Two requests reading the same counter would otherwise issue the same number.
+- A back-dated invoice is fine inside the current period but refused if it falls in an earlier one, so it cannot reuse a number.
+- `checkGstFormat` tests Rule 46: at most 16 characters, only letters, digits, `/` and `-`. `INV/2025-26/00042` is 17 characters and fails, so size your pattern for it.
+
+Not included: credit-note or debit-note series, multiple series per branch (use one counter per series), and gap detection.

package/dist/index.cjs

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  checkGstFormat: () => checkGstFormat,
+  financialYear: () => financialYear,
+  format: () => format,
+  next: () => next
+});
+module.exports = __toCommonJS(index_exports);
+function parseDate(date) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!m) throw new Error(`Invalid date "${date}", expected YYYY-MM-DD`);
+  const [y, mo, d] = [+m[1], +m[2], +m[3]];
+  if (new Date(Date.UTC(y, mo - 1, d)).toISOString().slice(0, 10) !== date) throw new Error(`Invalid date "${date}"`);
+  return { y, m: mo };
+}
+function financialYear(date, fyStartMonth = 4) {
+  if (!Number.isInteger(fyStartMonth) || fyStartMonth < 1 || fyStartMonth > 12) throw new Error("fyStartMonth must be between 1 and 12");
+  const { y, m } = parseDate(date);
+  if (fyStartMonth === 1) return String(y);
+  const start = m >= fyStartMonth ? y : y - 1;
+  return `${start}-${String((start + 1) % 100).padStart(2, "0")}`;
+}
+function periodKey(date, f) {
+  const { y, m } = parseDate(date);
+  switch (f.reset ?? "financial-year") {
+    case "financial-year":
+      return financialYear(date, f.fyStartMonth ?? 4);
+    case "calendar-year":
+      return String(y);
+    case "month":
+      return `${y}-${String(m).padStart(2, "0")}`;
+    case "never":
+      return "all";
+  }
+}
+var TOKEN = /\{(FY2|FY|YYYY|YY|MM|SEQ)(?::(\d{1,2}))?\}/g;
+function format(seq, date, f) {
+  if (!Number.isInteger(seq) || seq < 1) throw new Error("seq must be a whole number of at least 1");
+  const { y, m } = parseDate(date);
+  const fy = financialYear(date, f.fyStartMonth ?? 4);
+  return f.pattern.replace(TOKEN, (_, token, width) => {
+    switch (token) {
+      case "FY":
+        return fy;
+      case "FY2":
+        return fy.includes("-") ? fy.slice(2, 4) + fy.slice(5) : fy.slice(2);
+      case "YYYY":
+        return String(y);
+      case "YY":
+        return String(y % 100).padStart(2, "0");
+      case "MM":
+        return String(m).padStart(2, "0");
+      default:
+        return String(seq).padStart(width ? Number(width) : 0, "0");
+    }
+  });
+}
+function next(counter, date, f) {
+  if (!/\{SEQ(?::\d{1,2})?\}/.test(f.pattern)) throw new Error("pattern must contain {SEQ} or {SEQ:n}");
+  const period = periodKey(date, f);
+  let seq;
+  if (!counter || counter.period !== period) {
+    if (counter && (f.reset ?? "financial-year") !== "never" && period < counter.period) {
+      throw new Error(`Date ${date} belongs to ${period}, which is before the current period ${counter.period}`);
+    }
+    seq = 1;
+  } else seq = counter.seq + 1;
+  return { number: format(seq, date, f), counter: { period, seq } };
+}
+function checkGstFormat(number) {
+  const problems = [];
+  if (number.length === 0) problems.push("Invoice number is empty");
+  if (number.length > 16) problems.push(`Invoice number is ${number.length} characters, the limit is 16`);
+  if (/[^A-Za-z0-9/-]/.test(number)) problems.push('Only letters, digits, "/" and "-" are allowed');
+  return { valid: problems.length === 0, problems };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkGstFormat,
+  financialYear,
+  format,
+  next
+});

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Dates are "YYYY-MM-DD" strings (plain calendar dates, no time zones).
+ *
+ * The package holds no state. You keep a small counter `{ period, seq }` in your database, call `next`
+ * inside the same transaction that saves the invoice, and store the counter it returns.
+ */
+type ResetPolicy = "financial-year" | "calendar-year" | "month" | "never";
+interface NumberFormat {
+    /**
+     * Pattern with tokens: {FY} 2025-26, {FY2} 2526, {YYYY}, {YY}, {MM}, and {SEQ:n} for the sequence
+     * padded to n digits ({SEQ} is unpadded). Example: "INV/{FY}/{SEQ:5}" -> "INV/2025-26/00042".
+     */
+    pattern: string;
+    /** When the sequence goes back to 1. Default "financial-year". */
+    reset?: ResetPolicy;
+    /** First month of the financial year. Default 4 (April), as in India. */
+    fyStartMonth?: number;
+}
+interface Counter {
+    /** The period the sequence belongs to, e.g. "2025-26". */
+    period: string;
+    /** The last sequence number used. */
+    seq: number;
+}
+/** Financial year label: financialYear("2025-03-31") -> "2024-25", financialYear("2025-04-01") -> "2025-26". */
+declare function financialYear(date: string, fyStartMonth?: number): string;
+/** Builds the invoice number for a given sequence and date. */
+declare function format(seq: number, date: string, f: NumberFormat): string;
+/**
+ * Gives the next number and the updated counter. Pass `null` for the very first invoice.
+ * If the date falls in a new period (new financial year, month...) the sequence restarts at 1.
+ * Dates earlier than the counter's period are refused, so a back-dated invoice cannot reuse a number.
+ */
+declare function next(counter: Counter | null, date: string, f: NumberFormat): {
+    number: string;
+    counter: Counter;
+};
+interface GstCheck {
+    valid: boolean;
+    problems: string[];
+}
+/**
+ * Checks the Indian GST rule for invoice numbers (Rule 46): at most 16 characters, only letters,
+ * digits, "/" and "-". Uniqueness within the financial year is up to your counter.
+ */
+declare function checkGstFormat(number: string): GstCheck;
+
+export { type Counter, type GstCheck, type NumberFormat, type ResetPolicy, checkGstFormat, financialYear, format, next };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Dates are "YYYY-MM-DD" strings (plain calendar dates, no time zones).
+ *
+ * The package holds no state. You keep a small counter `{ period, seq }` in your database, call `next`
+ * inside the same transaction that saves the invoice, and store the counter it returns.
+ */
+type ResetPolicy = "financial-year" | "calendar-year" | "month" | "never";
+interface NumberFormat {
+    /**
+     * Pattern with tokens: {FY} 2025-26, {FY2} 2526, {YYYY}, {YY}, {MM}, and {SEQ:n} for the sequence
+     * padded to n digits ({SEQ} is unpadded). Example: "INV/{FY}/{SEQ:5}" -> "INV/2025-26/00042".
+     */
+    pattern: string;
+    /** When the sequence goes back to 1. Default "financial-year". */
+    reset?: ResetPolicy;
+    /** First month of the financial year. Default 4 (April), as in India. */
+    fyStartMonth?: number;
+}
+interface Counter {
+    /** The period the sequence belongs to, e.g. "2025-26". */
+    period: string;
+    /** The last sequence number used. */
+    seq: number;
+}
+/** Financial year label: financialYear("2025-03-31") -> "2024-25", financialYear("2025-04-01") -> "2025-26". */
+declare function financialYear(date: string, fyStartMonth?: number): string;
+/** Builds the invoice number for a given sequence and date. */
+declare function format(seq: number, date: string, f: NumberFormat): string;
+/**
+ * Gives the next number and the updated counter. Pass `null` for the very first invoice.
+ * If the date falls in a new period (new financial year, month...) the sequence restarts at 1.
+ * Dates earlier than the counter's period are refused, so a back-dated invoice cannot reuse a number.
+ */
+declare function next(counter: Counter | null, date: string, f: NumberFormat): {
+    number: string;
+    counter: Counter;
+};
+interface GstCheck {
+    valid: boolean;
+    problems: string[];
+}
+/**
+ * Checks the Indian GST rule for invoice numbers (Rule 46): at most 16 characters, only letters,
+ * digits, "/" and "-". Uniqueness within the financial year is up to your counter.
+ */
+declare function checkGstFormat(number: string): GstCheck;
+
+export { type Counter, type GstCheck, type NumberFormat, type ResetPolicy, checkGstFormat, financialYear, format, next };

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/index.ts
+function parseDate(date) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!m) throw new Error(`Invalid date "${date}", expected YYYY-MM-DD`);
+  const [y, mo, d] = [+m[1], +m[2], +m[3]];
+  if (new Date(Date.UTC(y, mo - 1, d)).toISOString().slice(0, 10) !== date) throw new Error(`Invalid date "${date}"`);
+  return { y, m: mo };
+}
+function financialYear(date, fyStartMonth = 4) {
+  if (!Number.isInteger(fyStartMonth) || fyStartMonth < 1 || fyStartMonth > 12) throw new Error("fyStartMonth must be between 1 and 12");
+  const { y, m } = parseDate(date);
+  if (fyStartMonth === 1) return String(y);
+  const start = m >= fyStartMonth ? y : y - 1;
+  return `${start}-${String((start + 1) % 100).padStart(2, "0")}`;
+}
+function periodKey(date, f) {
+  const { y, m } = parseDate(date);
+  switch (f.reset ?? "financial-year") {
+    case "financial-year":
+      return financialYear(date, f.fyStartMonth ?? 4);
+    case "calendar-year":
+      return String(y);
+    case "month":
+      return `${y}-${String(m).padStart(2, "0")}`;
+    case "never":
+      return "all";
+  }
+}
+var TOKEN = /\{(FY2|FY|YYYY|YY|MM|SEQ)(?::(\d{1,2}))?\}/g;
+function format(seq, date, f) {
+  if (!Number.isInteger(seq) || seq < 1) throw new Error("seq must be a whole number of at least 1");
+  const { y, m } = parseDate(date);
+  const fy = financialYear(date, f.fyStartMonth ?? 4);
+  return f.pattern.replace(TOKEN, (_, token, width) => {
+    switch (token) {
+      case "FY":
+        return fy;
+      case "FY2":
+        return fy.includes("-") ? fy.slice(2, 4) + fy.slice(5) : fy.slice(2);
+      case "YYYY":
+        return String(y);
+      case "YY":
+        return String(y % 100).padStart(2, "0");
+      case "MM":
+        return String(m).padStart(2, "0");
+      default:
+        return String(seq).padStart(width ? Number(width) : 0, "0");
+    }
+  });
+}
+function next(counter, date, f) {
+  if (!/\{SEQ(?::\d{1,2})?\}/.test(f.pattern)) throw new Error("pattern must contain {SEQ} or {SEQ:n}");
+  const period = periodKey(date, f);
+  let seq;
+  if (!counter || counter.period !== period) {
+    if (counter && (f.reset ?? "financial-year") !== "never" && period < counter.period) {
+      throw new Error(`Date ${date} belongs to ${period}, which is before the current period ${counter.period}`);
+    }
+    seq = 1;
+  } else seq = counter.seq + 1;
+  return { number: format(seq, date, f), counter: { period, seq } };
+}
+function checkGstFormat(number) {
+  const problems = [];
+  if (number.length === 0) problems.push("Invoice number is empty");
+  if (number.length > 16) problems.push(`Invoice number is ${number.length} characters, the limit is 16`);
+  if (/[^A-Za-z0-9/-]/.test(number)) problems.push('Only letters, digits, "/" and "-" are allowed');
+  return { valid: problems.length === 0, problems };
+}
+export {
+  checkGstFormat,
+  financialYear,
+  format,
+  next
+};

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@zenuinebit/invoice-number",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Sequential invoice numbers with financial-year resets and GST-compliant format checks.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }