@stacksjs/datetime 0.70.23 → 0.70.25

package/README.md

@@ -1,15 +1,17 @@
 # Stacks Datetime
 
-Easily work with dates.
+Easily work with dates. Zero external dependencies, Carbon-inspired API.
 
-## ☘️ Features
+## Features
 
+- Carbon-inspired `DateTime` class with fluent chainable API
 - Display & visualize dates in a human-friendly way
 - Easily convert dates to different formats & timezones
 - Simply calculate the difference between 2 dates
-- Modify dates with ease
+- Modify dates with ease (immutable operations)
+- Zero external dependencies
 
-## 🤖 Usage
+## Usage
 
 ```bash
 bun install -d @stacksjs/datetime
@@ -18,29 +20,49 @@ bun install -d @stacksjs/datetime
 Now, you can easily access it in your project:
 
 ```js
-import { now, useDateFormat } from '@stacksjs/datetime'
-
-const formatted = useDateFormat(now(), 'YYYY-MM-DD HH:mm:ss')
-console.log(formatted) // 2022-11-01 17:06:01
+import { DateTime, now } from '@stacksjs/datetime'
+
+// Laravel-inspired now() helper
+now().toDateString()         // '2024-03-15'
+now().format('MMMM D, YYYY') // 'March 15, 2024'
+now().addDays(7).toDateString()
+now().startOfMonth().toDateString()
+
+// DateTime class
+const dt = DateTime.create(2024, 3, 15, 10, 30, 0)
+dt.format('YYYY-MM-DD HH:mm:ss') // '2024-03-15 10:30:00'
+dt.addHours(3).toTimeString()     // '13:30:00'
+dt.isFuture()                     // depends on current time
+dt.diffInDays(DateTime.now())     // days between dates
+
+// Parse dates
+DateTime.parse('2024-03-15', 'YYYY-MM-DD')
+DateTime.parse('March 15, 2024', 'MMMM D, YYYY')
+
+// Standalone format/parse functions
+import { format, parse } from '@stacksjs/datetime'
+format(new Date(), 'YYYY-MM-DD HH:mm:ss')
+format(new Date(), 'MMMM D, YYYY', { tz: 'Asia/Tokyo' })
+parse('2024-03-15 10:30:00', 'YYYY-MM-DD HH:mm:ss')
 ```
 
-To view the full documentation, please visit [https://stacksjs.org/datetime](https://stacksjs.org/datetime).
+To view the full documentation, please visit [<https://stacksjs.com/datetim>e](https://stacksjs.com/datetime).
 
-## 🧪 Testing
+## Testing
 
 ```bash
 bun test
 ```
 
-## 📈 Changelog
+## Changelog
 
 Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
 
-## 🚜 Contributing
+## Contributing
 
 Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
 
-## 🏝 Community
+## Community
 
 For help, discussion about best practices, or any other conversation that would benefit from being searchable:
 
@@ -50,16 +72,15 @@ For casual chit-chat with others using this package:
 
 [Join the Stacks Discord Server](https://discord.gg/stacksjs)
 
-## 🙏🏼 Credits
+## Credits
 
 Many thanks to the following core technologies & people who have contributed to this package:
 
-- [VueUse](https://vueuse.org)
 - [Carbon](https://carbon.nesbot.com)
 - [Chris Breuer](https://github.com/chrisbbreuer)
 - [All Contributors](../../contributors)
 
-## 📄 License
+## License
 
 The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
 

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-import{useDateFormat as RG,useNow as LG}from"@stacksjs/utils";var i=/^([0-9]{4})-([0-1][0-9])(?:-([0-3][0-9]))?(?:[T ]?([0-2][0-9])(?::([0-5][0-9]))?(?::([0-5][0-9]))?)?(?:\.[0-9]+)?(Z|(?:\+|\-)[0-9]{2}:?[0-9]{2})?$/;function d(G){let J=G.match(i);if(J){let Q=Number(J[2]);if(Q<1||Q>12)return!1;if(typeof J[3]!==void 0){let X=Number(J[3]);if(X<1||X>31)return!1}if(typeof J[4]!==void 0){let X=Number(J[4]);if(X<0||X>23)return!1}return!0}return!1}function VG(G){let J=G.match(i);if(J&&typeof J[4]==="undefined")return G+="T00:00:00";return G}function q(G){if(!G)G=new Date;if(G instanceof Date){let J=new Date(G);return J.setMilliseconds(0),J}if(G=G.trim(),d(G))return new Date(VG(G));throw new Error(`Non ISO 8601 compliant date (${G}).`)}function p(G){let J=q(G);return J.setDate(1),J.setMonth(J.getMonth()+1),J.setDate(0),J}function P(G){return p(G).getDate()}var v="1999-03-04T02:05:01.000Z",k=new Map,M=[["YYYY",{year:"numeric"}],["YY",{year:"2-digit"}],["MMMM",{month:"long"}],["MMM",{month:"short"}],["MM",{month:"2-digit"}],["M",{month:"numeric"}],["DD",{day:"2-digit"}],["D",{day:"numeric"}],["dddd",{weekday:"long"}],["ddd",{weekday:"short"}],["d",{weekday:"narrow"}],["mm",{minute:"2-digit"}],["m",{minute:"numeric"}],["ss",{second:"2-digit"}],["s",{second:"numeric"}],["ZZ",{timeZoneName:"long"}],["Z",{timeZoneName:"short"}]],g=[["HH",{hour:"2-digit"}],["H",{hour:"numeric"}]],h=[["hh",{hour:"2-digit"}],["h",{hour:"numeric"}],["a",{dayPeriod:"narrow"}],["A",{dayPeriod:"narrow"}]],L={DD:2,HH:2,MM:2,YY:2,YYYY:4,hh:2,mm:2,ss:2};function D(G){if(/^[+-]\d{2}:\d{2}/.test(G))return 6;if(/^[+-]\d{4}/.test(G))return 5;throw new Error("Invalid offset format")}var TG=["MMMM","MMM","dddd","ddd"],I=new Map([...M,...g,...h].map((G)=>{return[G[0],G]})),n=new Map,j=["full","long","medium","short"],A=(G)=>String(G).padStart(2,"0"),c=(G)=>String(G).padStart(2,"0");function E(G){if(G.type==="literal")G.value=G.value.normalize("NFKC");return G}function KG(G,J,Q,X=!1,K=null){let $=zG(G,J,Q,X),F=q(G);function _({partName:W,partValue:Z,token:b}){if(W==="literal")return Z;let C=$[W];if(W==="hour"&&b==="H")return C.replace(/^0/,"")||"0";if(["mm","ss","MM"].includes(b)&&C.length===1)return`0${C}`;if(W==="dayPeriod"){let N=x(F.getUTCHours()<12?"am":"pm",Q);return b==="A"?N.toUpperCase():N.toLowerCase()}if(W==="timeZoneName")return K!=null?K:o(-1*F.getTimezoneOffset(),b);return C}return J.map((W)=>{return{...W,value:_(W)}})}function zG(G,J,Q,X=!1){let K=q(G),$=J.filter((b)=>b.hour12),F=J.filter((b)=>!b.hour12),_=[],W=[];function Z(b,C=!1){let N=`${Q}-u-hc-${C?"h12":"h23"}`;if(_.push(...new Intl.DateTimeFormat(N,b.reduce((H,V)=>{if(V.partName==="literal")return H;if(X&&TG.includes(V.token))W.push(V);return Object.assign(H,V.option)},{timeZone:"UTC"})).formatToParts(K).map(E)),X&&W.length)for(let H of W){let V=[];switch(H.token){case"MMMM":V=new Intl.DateTimeFormat(N,{dateStyle:"long",timeZone:"UTC"}).formatToParts(K).map(E);break;case"MMM":V=new Intl.DateTimeFormat(N,{dateStyle:"medium",timeZone:"UTC"}).formatToParts(K).map(E);break}let T=V.find((Y)=>Y.type===H.partName),R=_.findIndex((Y)=>Y.type===H.partName);if(T&&R>-1)_[R]=T}}if($.length)Z($,!0);if(F.length)Z(F);return _.reduce((b,C)=>{return b[C.type]=C.value,b},{})}function o(G,J="Z"){let Q=String(Math.floor(Math.abs(G/60))).padStart(2,"0"),X=String(Math.abs(G%60)).padStart(2,"0"),K=G<0?"-":"+";if(J==="ZZ")return`${K}${Q}${X}`;return`${K}${Q}:${X}`}function QG(G,J){s(G,J);let[Q,X,K,$]=G.match(/([+-])([0-3][0-9]):?([0-6][0-9])/),F=Number(K)*60+Number($);return X==="+"?F:-F}function s(G,J="Z"){if(!((X)=>{switch(X){case"Z":return/^([+-])[0-3][0-9]:[0-6][0-9]$/.test(G);case"ZZ":return/^([+-])[0-3][0-9][0-6][0-9]$/.test(G)}})(J))throw new Error(`Invalid offset: ${G}`);return G}function XG(G){return M.concat(g).concat(h).sort((J,Q)=>J[0].length>Q[0].length?1:-1).reduce((J,Q)=>{return J.replace(Q[0],`\\${Q[0]}`)},G)}function wG(G){return["numeric","2-digit"].includes(G.partValue)}function $G(G){let J=void 0;for(let Q of G){if(Q.partName==="literal"&&!isNaN(parseFloat(Q.partValue)))throw new Error(`Numbers in format (${Q.partValue}).`);if(J&&J.partName!=="literal"&&Q.partName!=="literal"){if(!(J.token in L)&&!(Q.token in L)&&!(wG(J)&&Q.token.toLowerCase()==="a"))throw new Error(`Illegal adjacent tokens (${J.token}, ${Q.token})`)}J=Q}return G}function bG(G){if(typeof G==="string")return G.includes("ZZ")?"ZZ":"Z";return"time"in G&&G.time==="full"?"Z":"ZZ"}function x(G,J){let Q=n.get(J);if(Q&&Q[G])return Q[G];let X=new Date(v);X.setUTCHours(G==="am"?5:20);let $=new Intl.DateTimeFormat(J,{timeStyle:"full",timeZone:"UTC",hour12:!0}).formatToParts(X).map(E).find((F)=>F.type==="dayPeriod");if($){let F=Q||{};return n.set(J,Object.assign(F,{[G]:$.value})),$.value}return G}function u(G,J="+00:00"){let Q=q(G),X=(()=>{switch(D(J)){case 5:return"ZZ";case 6:return"Z"}})(),K=QG(J,X);return new Date(Q.getTime()+K*1000*60)}function l(){return Intl.DateTimeFormat().resolvedOptions().timeZone}function qG(G,J){let Q=new Intl.DateTimeFormat("en-US",{year:"numeric",month:"2-digit",day:"2-digit",hour:"2-digit",minute:"2-digit",second:"2-digit",timeZone:J,hourCycle:"h23"}).formatToParts(G).map(E),X={};return Q.forEach((K)=>{X[K.type]=K.value}),new Date(`${X.year}-${X.month}-${X.day}T${X.hour}:${X.minute}:${X.second}Z`)}function S(G,J="UTC",Q="device",X="Z"){var K;Q=Q==="device"?(K=l())!=null?K:"utc":Q;let $=q(G),F=qG($,J),_=qG($,Q),W=Math.round((_.getTime()-F.getTime())/1000/60);return o(W,X)}function U(G,J){if(j.includes(G)||typeof G==="object")return EG(G,J);let Q=G,X=0,K=(b)=>{if(!b[2])b[2]=new RegExp(`(.)?(${b[0]})`,"g");if(b[2].test(Q)){let C=0;return Q=Q.replace(b[2],(N,H,V)=>{if(H==="\\")return V;return`${typeof H==="string"?H:""}{!${C++?X:X++}!}`}),!!C}return!1};function $(b){let C=b.map((H)=>H.partName),N=new Set(C);if(C.length>N.size)throw new Error("Cannot reuse format tokens.");return b}function F(b,[C,N,H]){let V=Object.keys(N)[0],T=N[V];return{option:N,partName:V,partValue:T,token:C,pattern:H,hour12:b}}let _=M.filter(K).concat(g.filter(K)).map(F.bind(null,!1)),W=$(_.concat(h.filter(K).map(F.bind(null,!0)))),Z=/^\{!(\d+)!\}$/;return Q.split(/(\{!\d+!\})/).map((b)=>{let C=b.match(Z);if(C)return W[Number(C[1])];return{option:{literal:b},partName:"literal",partValue:b,token:b,pattern:new RegExp(""),hour12:!1}}).filter((b)=>!(b.partName==="literal"&&b.partValue===""))}function EG(G,J){let Q={timeZone:"UTC"};if(typeof G==="string")Q.dateStyle=G;else{if("date"in G)Q.dateStyle=G.date;if("time"in G)Q.timeStyle=G.time}let X=new Intl.DateTimeFormat(J,Q),K=X.formatToParts(new Date(v)).map(E),F=X.formatToParts(new Date("1999-04-05T23:05:01.000Z")).map(E).find((W)=>W.type==="hour"),_=F&&F.value==="23"?24:12;return K.map((W)=>{let Z=W.type,b=YG(W.type,W.value,J,W.type==="hour"?_:void 0,Q);if(b===void 0)return;let C=b[1][Z];if(!C)return;if(!b[2])b[2]=new RegExp(`${b[0]}`,"g");return{option:{[Z]:C},partName:Z,partValue:C,token:b[0],pattern:b[2],hour12:_===12}}).filter((W)=>!!W)}function YG(G,J,Q,X,K){let $=J.length,F=!isNaN(Number(J)),_;switch(G){case"year":return $===2?I.get("YY"):I.get("YYYY");case"month":if(F)return $===1?I.get("M"):I.get("MM");switch(_=CG(Q,G,J),_){case"long":return I.get("MMMM");default:return I.get("MMM")}case"day":return $===1?I.get("D"):I.get("DD");case"weekday":switch(_=CG(Q,G,J),_){case"narrow":return I.get("d");case"short":return I.get("ddd");default:return I.get("dddd")}case"hour":if(X===12)return $===1?I.get("h"):I.get("hh");return $===1?I.get("H"):I.get("HH");case"minute":return $===1?I.get("m"):I.get("mm");case"second":return $===1?I.get("s"):I.get("ss");case"dayPeriod":return/^[A-Z]+$/u.test(J)?I.get("A"):I.get("a");case"literal":return[J,{literal:J},new RegExp("")];case"timeZoneName":return K.timeStyle==="full"?I.get("Z"):I.get("ZZ");default:return}}function CG(G,J,Q){if(!k.has(G)){let K=new Date(v),$=[3,8,9,7,6,4,3],F=["weekday","month","dayPeriod"],_=["long","short","narrow"],W={};for(let Z=0;Z<12;Z++){if(K.setMonth(0+Z),Z in $)K.setDate($[Z]);K.setUTCHours(8+Z);for(let b of _){let C=new Intl.DateTimeFormat(G,F.reduce((N,H)=>Object.assign(N,{[H]:b}),{hour12:!0,timeZone:"UTC"})).formatToParts(K).map(E);if(b==="long"||b==="short"){let H=new Intl.DateTimeFormat(G,{dateStyle:b==="short"?"medium":"long",timeZone:"UTC"}).formatToParts(K).map(E).find((T)=>T.type==="month"),V=C.findIndex((T)=>T.type==="month");if(V>-1&&H)C[V]=H}C.forEach((N)=>{if(N.type==="literal")return;let H=N.type;W[H]=Object.assign(W[H]||{},{[N.value]:b})})}}k.set(G,W)}let X=k.get(G);return X?X[J][Q]:void 0}function r(G,J="+00:00"){let Q=J.slice(0,1)==="+";return u(G,J.replace(Q?"+":"-",Q?"-":"+"))}function FG(){return Intl.DateTimeFormat().resolvedOptions().locale}function B(G,J="long",Q="device",X=!1,K){let $,F;if(typeof G==="object"&&!(G instanceof Date))({date:G,format:J,locale:Q,genitive:X,partFilter:K,tz:$}=G);if(J==="ISO8601")return q(G).toISOString();if($)F=S(G,"utc",$,bG(J));if($!=null||($=l()),($==null?void 0:$.toLowerCase())!=="utc")G=r(G,S(G,$,"utc"));if(!Q||Q==="device")Q=FG();return KG(G,U(J,Q).filter(K!=null?K:()=>!0),Q,X,F).map((_)=>_.value).join("")}function e(G,J="en",Q=!1,X=()=>!0){return U(G,J).filter(X).reduce((K,$)=>K+=Q&&$.partName==="literal"?XG($.token):$.token,"").normalize("NFKC")}function a(G){let J=new Date().getFullYear(),Q=J%100,X=Math.floor(J/100),K=Number(G);return(X+(K>Q+20?-1:0))*100+K}function f(G,J="en",Q=!1){let X=(K,$)=>Array(K).fill("").map((F,_)=>`${$(_)}`);if(G==="M")return X(12,(K)=>K+1);if(G==="MM")return X(12,(K)=>{let $=K+1;return $<10?`0${$}`:$});if(G.startsWith("M"))return f("MM").map((K)=>B(`2000-${K}-05`,G,J,Q));if(G.startsWith("d"))return X(7,(K)=>`0${K+2}`).map((K)=>B(`2022-10-${K}`,G,J));if(G==="a")return[x("am",J).toLowerCase(),x("pm",J).toLowerCase()];if(G==="A")return[x("am",J).toUpperCase(),x("pm",J).toUpperCase()];if(G.startsWith("Y")){let K=new Date().getFullYear();return X(120,($)=>$+1).reduce(($,F)=>{if(F!=="120")$.push(B(`${K+Number(F)}-06-06`,G,J));return $.unshift(B(`${K-Number(F)}-06-06`,G,J)),$},[B(`${K}-06-06`,G,J)])}if(G.startsWith("D"))return X(31,(K)=>`${G==="DD"&&K<9?"0":""}${K+1}`);if(G.startsWith("H"))return X(24,(K)=>`${G==="HH"&&K<10?"0":""}${K}`);if(G.startsWith("h"))return X(12,(K)=>`${G==="hh"&&K<9?"0":""}${K+1}`);if(G.startsWith("m")||G.startsWith("s"))return X(60,(K)=>`${G.length>1&&K<10?"0":""}${K}`);return[]}function WG(G,J="ISO8601",Q="device"){let X=()=>!0,K,$="backward";if(typeof G==="object")({date:K,format:J="ISO8601",locale:Q="device",dateOverflow:$="backward",partFilter:X=()=>!0}=G);else K=G;if(!K)throw new Error("parse() requires a date string.");let F=()=>{throw new Error(`Date (${K}) does not match format (${e(J,Q)})`)};if(J==="ISO8601")return q(K);let _=j.includes(J)||typeof J==="object",W=$G(U(J,Q).filter(X));if(!W.length)throw new Error("parse() requires a pattern.");let Z;try{Z=_G(K,W)}catch{return F()}let b=new Date,C=new Map([["YYYY",b.getFullYear()],["MM",b.getMonth()+1],["DD",b.getDate()],["HH",0],["mm",0],["ss",0]]),N=null,H="";Z.forEach((z)=>{if(z.partName==="literal")return;if(z.token===z.value)return F();let y=Number(z.value);if(C.has(z.token))C.set(z.token,y);else if(z.token==="YY")C.set("YYYY",a(z.value));else{let w=z.token;if(w.startsWith("d"))return;else if(w==="D")C.set("DD",y);else if(w==="H"||w.startsWith("h"))C.set("HH",y);else if(w==="M")C.set("MM",y);else if(w==="a"||w==="A")N=z.value.toLowerCase()===x("am",Q).toLowerCase();else if(w==="Z"||w==="ZZ")H=s(z.value,w);else{let JG=f(w,Q,_).indexOf(z.value);if(JG!==-1)switch(w){case"MMM":case"MMMM":C.set("MM",JG+1);break}}}});let V=C.get("HH")||0;if(N===!1)V+=V===12?0:12,C.set("HH",V===24?0:V);else if(N===!0&&V===12)C.set("HH",0);C.set("MM",(C.get("MM")||1)-1);let[T,R,Y,ZG,HG,NG]=Array.from(C.values()),t=P(new Date(`${c(T)}-${A(R+1)}-10`));if(t<Y&&$==="throw")throw new Error(`Invalid date ${c(T)}-${A(R+1)}-${A(Y)}`);Y=$==="backward"?Math.min(Y,t):Y;let IG=`${c(T)}-${A(R+1)}-${A(Y)}T${A(ZG)}:${A(HG)}:${A(NG)}${H}`,GG=new Date(IG);if(isFinite(+GG))return GG;return F()}function _G(G,J){let Q=0,X=(_)=>[_[Q++],_[Q]],K=0,$=[],F=void 0;do{let[_,W]=X(J);F=W;let Z=1;if(_.partName==="literal")Z=_.partValue.length;else if(_.partName==="timeZoneName")Z=D(G.substring(K));else if(_.token in L)Z=L[_.token];else if(W)if(W.partName==="literal"){if(Z=G.indexOf(W.partValue,K)-K,Z<0)throw new Error}else if(W.partName==="dayPeriod"){for(let b=1;b<=4;b++)if(isNaN(Number(G.charAt(K+b)))){Z=b;break}}else{let b=G.substring(K).search(/\d/);if(b!==-1)Z=K+b}else Z=G.length;$.push({..._,value:G.substring(K,K+Z)}),K+=Z}while(F);return $}var jX=LG,cX=RG;export{WG as parse,jX as now,B as format,cX as dateFormat};
+export{E as parse,z as now,B as format,I as dateFormat,y as DateTime};

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/datetime",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.25",
   "description": "The Stacks datetime helpers.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/datetime#readme",
@@ -16,26 +18,39 @@
   "bugs": {
     "url": "https://github.com/stacksjs/stacks/issues"
   },
-  "keywords": ["datetime", "date", "time", "helpers", "composables", "stacks"],
+  "keywords": [
+    "datetime",
+    "date",
+    "time",
+    "helpers",
+    "composables",
+    "stacks"
+  ],
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@formkit/tempo": "^0.1.2",
-    "@stacksjs/development": "0.70.22",
-    "@stacksjs/utils": "0.70.22"
-  }
+    "better-dx": "^0.2.12",
+    "@stacksjs/utils": "0.70.23"
+  },
+  "sideEffects": false
 }