@blueprint-ts/core 3.0.0 → 4.0.0-beta.10

package/docs/vue/forms/state-and-properties.md

@@ -0,0 +1,26 @@
+# State And Properties
+
+`BaseForm` tracks the original state and the current state of each field.
+
+```ts
+form.isDirty() // any field modified
+form.isDirty('email') // specific field modified
+
+form.touch('email')
+form.isTouched('email')
+```
+
+**Properties**
+
+`properties.<field>` exposes:
+- `model` (a `ComputedRef` compatible with `v-model`)
+- `errors` (array)
+- `dirty` and `touched`
+
+Example:
+
+```vue
+<input v-model="form.properties.email.model.value" />
+<div v-if="form.properties.email.dirty">This field has been changed</div>
+<div v-if="form.properties.email.errors.length">{{ form.properties.email.errors[0] }}</div>
+```

package/docs/vue/forms/utilities.md

@@ -0,0 +1,27 @@
+# Utilities
+
+Update multiple fields at once:
+
+```ts
+form.fillState({ name: 'John Doe', email: 'john@example.com' })
+```
+
+Synchronize a value without marking dirty:
+
+```ts
+form.syncValue('email', 'new@example.com')
+```
+
+Reset the form to its original state:
+
+```ts
+form.reset()
+```
+
+Convert `properties` back to raw data:
+
+```ts
+import { propertyAwareToRaw } from '@blueprint-ts/core/vue/forms'
+
+const raw = propertyAwareToRaw<FormState>(form.properties)
+```

package/docs/vue/forms/validation.md

@@ -0,0 +1,189 @@
+# Validation
+
+Define validation rules by overriding `defineRules()` in your form class.
+
+Validation errors are exposed on `properties.<field>.errors`, as documented in [Errors](/vue/forms/errors).
+
+## Available Rules
+
+- `RequiredRule` — checks that the value is not `null`, `undefined`, or `''`
+- `MinRule` — minimum length for strings/arrays or minimum value for numbers
+- `ConfirmedRule` — validates that two fields match (e.g. password confirmation)
+- `UrlRule` — validates that the value is a valid URL
+- `EmailRule` — validates that the value is a valid email address
+- `JsonRule` — validates that the value is valid JSON
+
+All rules are exported from `@blueprint-ts/core/vue/forms/validation`.
+
+## Validation Modes
+
+Validation modes are bit flags. You can use the presets below or combine flags with `|`.
+
+**Flags**
+
+- `ValidationMode.NEVER` — never validate this field
+- `ValidationMode.INSTANTLY` — validate immediately when the field is evaluated, even if not dirty/touched
+- `ValidationMode.ON_TOUCH` — validate after the field is touched
+- `ValidationMode.ON_DIRTY` — validate when the field becomes dirty
+- `ValidationMode.ON_SUBMIT` — validate on submit
+- `ValidationMode.ON_DEPENDENT_CHANGE` — validate when a dependent field changes
+
+**Presets**
+
+- `ValidationMode.DEFAULT` — `ON_TOUCH | ON_DIRTY | ON_SUBMIT`
+- `ValidationMode.AGGRESSIVE` — `INSTANTLY | ON_TOUCH | ON_DIRTY | ON_SUBMIT`
+- `ValidationMode.PASSIVE` — `ON_SUBMIT`
+
+**Custom Combination**
+
+```ts
+options: { mode: ValidationMode.ON_TOUCH | ValidationMode.ON_SUBMIT }
+```
+
+**Internal vs External**
+
+- Internal means validation runs from within `BaseForm` based on user interaction or dependencies.
+- External means you explicitly trigger validation via `validate(true)`, typically on submit.
+
+- Internal triggers: `INSTANTLY`, `ON_TOUCH`, `ON_DIRTY`, `ON_DEPENDENT_CHANGE`
+- External trigger (`validate(true)`): `ON_SUBMIT` (and `PASSIVE` preset)
+- `NEVER` disables validation entirely
+
+Rules can declare dependencies via `rule.dependsOn = ['otherField']`. Some rules, such as `ConfirmedRule`, automatically set up bidirectional dependencies.
+
+## Externally Triggering Validation
+
+```ts
+const ok = form.validate(true)
+if (!ok) return
+```
+
+Some modes (notably `PASSIVE` / `ON_SUBMIT`) only validate when you trigger validation manually.
+
+### How `validate(isSubmitting)` Behaves
+
+- `validate(true)` enables `ON_SUBMIT` rules. Fields with `PASSIVE` mode will validate only here.
+- `validate(false)` still validates fields that are currently dirty, touched, or set to `INSTANTLY`.
+- `ValidationMode.NEVER` prevents validation in all cases, even during submit.
+
+## Typing `defineRules`
+
+Use `ValidationRules<FormBody>` for a concise, strongly-typed return type:
+
+```ts
+import { type ValidationRules } from '@blueprint-ts/core/vue/forms/validation'
+
+protected override defineRules(): ValidationRules<MyFormBody> {
+  return {
+    // ...
+  }
+}
+```
+
+## Custom Rules
+
+Create your own rules by extending `BaseRule`:
+
+```ts
+import { BaseRule } from '@blueprint-ts/core/vue/forms/validation'
+
+export class MaxRule<FormBody extends object> extends BaseRule<FormBody> {
+  public constructor(
+    protected max: number,
+    protected message: string = 'Value is too large'
+  ) {
+    super()
+  }
+
+  public validate(value: unknown): boolean {
+    if (value === null || value === undefined) {
+      return true
+    }
+
+    if (typeof value === 'string') {
+      return value.length <= this.max
+    }
+
+    if (typeof value === 'number') {
+      return value <= this.max
+    }
+
+    if (Array.isArray(value)) {
+      return value.length <= this.max
+    }
+
+    return false
+  }
+
+  public getMessage(): string {
+    return this.message
+  }
+}
+```
+
+If a rule depends on other fields, set `dependsOn` or implement bidirectional validation:
+
+```ts
+import { BaseRule } from '@blueprint-ts/core/vue/forms/validation'
+import { type BidirectionalRule } from '@blueprint-ts/core/vue/forms/validation'
+
+export class MatchesOtherRule<FormBody extends object> extends BaseRule<FormBody> implements BidirectionalRule {
+  public dependsOn: Array<keyof FormBody> = ['other']
+
+  public validate(value: unknown, state: FormBody): boolean {
+    return value === state['other' as keyof FormBody]
+  }
+
+  public getMessage(): string {
+    return 'Values do not match'
+  }
+
+  public getBidirectionalFields(): string[] {
+    return ['other']
+  }
+}
+```
+
+## Example
+
+```ts
+import { BaseForm } from '@blueprint-ts/core/vue/forms'
+import { ConfirmedRule, MinRule, RequiredRule, type ValidationRules } from '@blueprint-ts/core/vue/forms/validation'
+
+export interface PinUpdateFormBody {
+  current_pin: string
+  new_pin: string
+  new_pin_confirmation: string
+}
+
+export class PinUpdateForm extends BaseForm<PinUpdateFormBody, PinUpdateFormBody> {
+  public constructor() {
+    super({
+      current_pin: '',
+      new_pin: '',
+      new_pin_confirmation: ''
+    })
+  }
+
+  protected override defineRules(): ValidationRules<PinUpdateFormBody> {
+    return {
+      current_pin: {
+        rules: [
+          new RequiredRule('This field is required.'),
+          new MinRule(4, 'This field must be at least 4 characters long.')
+        ]
+      },
+      new_pin: {
+        rules: [
+          new RequiredRule('This field is required.'),
+          new MinRule(4, 'This field must be at least 4 characters long.'),
+          new ConfirmedRule('new_pin_confirmation', 'This field must match the confirmation.')
+        ]
+      },
+      new_pin_confirmation: {
+        rules: [new RequiredRule('This field is required.')]
+      }
+    }
+  }
+}
+```

package/docs/vue/requests/loading.md

@@ -0,0 +1,51 @@
+# Loading
+
+For Vue apps, the library includes `VueRequestLoader`, `VueRequestLoaderFactory`, and `VueRequestBatchLoader`, which
+use Vue refs to track loading state.
+
+## Registering the Vue Loader Factory
+
+```typescript
+import { BaseRequest } from '@blueprint-ts/core/requests'
+import { VueRequestLoaderFactory } from '@blueprint-ts/core/vue/requests'
+
+BaseRequest.setRequestLoaderFactory(new VueRequestLoaderFactory())
+```
+
+## Reading Loading State
+
+```typescript
+const request = new ExpenseIndexRequest()
+
+request.send()
+
+const isLoading = request.isLoading()
+// isLoading is a Ref<boolean> when using VueRequestLoaderFactory
+```
+
+## Batch Loading
+
+`VueRequestBatchLoader` can track the loading state of multiple requests. Use it when you want a single loading ref to
+reflect a batch of requests.
+
+```typescript
+import { VueRequestBatchLoader } from '@blueprint-ts/core/vue/requests'
+
+const batchLoader = new VueRequestBatchLoader(2)
+batchLoader.startBatch(2)
+
+const requestA = new ExpenseIndexRequest().setRequestLoader(batchLoader)
+const requestB = new ExpenseIndexRequest().setRequestLoader(batchLoader)
+
+requestA.send()
+requestB.send()
+
+const isLoading = batchLoader.isLoading()
+```
+
+If the batch will not complete (for example, when a chained request fails), call `abortBatch()` to stop waiting for the
+remaining requests:
+
+```typescript
+batchLoader.abortBatch()
+```

package/docs/vue/{requests → router}/route-resource-binding.md

@@ -7,7 +7,7 @@ When using `vue-router`, you can automatically bind route parameters to resource
 To enable the router to load resources automatically, install the route injection plugin when initializing your router:
 
 ```ts
-import { installRouteInjection } from '@blueprint-ts/core'
+import { installRouteInjection } from '@blueprint-ts/core/vue/router/routeResourceBinding'
 
 installRouteInjection(router)
 ```
@@ -17,7 +17,7 @@ installRouteInjection(router)
 Use the `defineRoute` helper to define your routes and specify which parameters should be resolved into resources:
 
 ```ts
-import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core/vue/router/routeResourceBinding'
 import ProductDetailPage from '@/pages/ProductDetailPage.vue'
 
 export default defineRoute<{
@@ -26,20 +26,22 @@ export default defineRoute<{
     path: ':productId',
     name: 'products.show',
     component: ProductDetailPage,
-    inject: {
-        product: {
-            from: 'productId',
-            resolve: (productId: string) => {
-                return new RouteResourceRequestResolver(
-                    new ProductShowRequest(productId)
-                )
+    meta: {
+        inject: {
+            product: {
+                from: 'productId',
+                resolve: (productId: string) => {
+                    return new RouteResourceRequestResolver(
+                            new ProductShowRequest(productId)
+                    )
+                }
             }
         }
     }
 })
 ```
 
-Navigation is **non-blocking** — the route navigates immediately while resources resolve in the background. Cached values are reused when navigating between child routes with unchanged parameters.
+Navigation is blocking by default. Cached values are reused when navigating between child routes with unchanged parameters.
 
 ## Usage in Components
 
@@ -60,7 +62,7 @@ const props = defineProps<{
 `RouteResourceBoundView` is a drop-in replacement for `<RouterView>` that automatically handles loading and error states. Define error and loading components directly in the route:
 
 ```ts
-import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core/vue/router/routeResourceBinding'
 import ProductDetailPage from '@/pages/ProductDetailPage.vue'
 import GenericErrorPage from '@/pages/GenericErrorPage.vue'
 import LoadingSpinner from '@/components/LoadingSpinner.vue'
@@ -73,13 +75,15 @@ export default defineRoute<{
     component: ProductDetailPage,
     errorComponent: GenericErrorPage,
     loadingComponent: LoadingSpinner,
-    inject: {
-        product: {
-            from: 'productId',
-            resolve: (productId: string) => {
-                return new RouteResourceRequestResolver(
-                    new ProductShowRequest(productId)
-                )
+    meta: {
+        inject: {
+            product: {
+                from: 'productId',
+                resolve: (productId: string) => {
+                    return new RouteResourceRequestResolver(
+                            new ProductShowRequest(productId)
+                    )
+                }
             }
         }
     }
@@ -94,7 +98,7 @@ Then replace `<RouterView>` with `<RouteResourceBoundView>` in your layout:
 </template>
 
 <script setup lang="ts">
-import { RouteResourceBoundView } from '@blueprint-ts/core'
+import { RouteResourceBoundView } from '@blueprint-ts/core/vue/router/routeResourceBinding'
 </script>
 ```
 
@@ -164,13 +168,15 @@ export default defineRoute<{
     name: 'products.show',
     component: ProductDetailPage,
     lazy: false,
-    inject: {
-        product: {
-            from: 'productId',
-            resolve: (productId: string) => {
-                return new RouteResourceRequestResolver(
-                    new ProductShowRequest(productId)
-                )
+    meta: {
+        inject: {
+            product: {
+                from: 'productId',
+                resolve: (productId: string) => {
+                    return new RouteResourceRequestResolver(
+                            new ProductShowRequest(productId)
+                    )
+                }
             }
         }
     }
@@ -192,7 +198,7 @@ Then use the `useRouteResource` composable inside your component:
 </template>
 
 <script setup lang="ts">
-import { useRouteResource } from '@blueprint-ts/core'
+import { useRouteResource } from '@blueprint-ts/core/vue/router/routeResourceBinding'
 
 const props = defineProps<{
     product: ProductResource

package/docs/vue/state.md

@@ -19,6 +19,9 @@ The `State` class provides a reactive, type-safe state management system with ri
 Create a new state by extending the base class and defining your interface:
 
 ```typescript
+import { State } from '@blueprint-ts/core/vue/state'
+import { type PersistenceDriver, LocalStorageDriver } from '@blueprint-ts/core/persistenceDrivers'
+
 // Define your state interface
 interface UserStateInterface {
   name: string;
@@ -42,14 +45,15 @@ class UserState extends State<UserStateInterface> {
         }
       }, 
       {
-        persist: true // Enable persistence
+        persist: true, // Enable persistence
+        persistSuffix: 'user' // Optional namespace for the storage key
       }
     );
   }
   
   // Optional: Override persistence method
   protected override getPersistenceDriver(): PersistenceDriver {
-    return new LocalStorageDriver();
+    return new LocalStorageDriver()
   }
 }
 
@@ -81,6 +85,16 @@ userState.subscribe(
 );
 ````
 
+`subscribe` returns an unsubscribe function:
+
+````typescript
+const unsubscribe = userState.subscribe('name', () => {
+  // ...
+});
+
+unsubscribe();
+````
+
 #### Subscribing to nested properties
 
 ````typescript
@@ -121,7 +135,7 @@ userState.subscribe(
 ````
 
 ### State Persistence
-Enable state persistence by passing `persist: true` in the constructor options. Override the method `getPersistenceDriver` to use different storage mechanisms:
+Enable state persistence by passing `persist: true` in the constructor options. You can optionally set `persistSuffix` to namespace the storage key. Override the method `getPersistenceDriver` to use different storage mechanisms:
 
 ````typescript
 // Examples of different persistence drivers:
@@ -137,6 +151,8 @@ protected override getPersistenceDriver(): PersistenceDriver {
 }
 ````
 
+You can inspect the computed key via `state.persistKey`.
+
 ### Importing and Exporting State
 
 Export the current state to a plain object or import values:
@@ -154,13 +170,6 @@ userState.import({
   }
 });
 
-// Import with hook suppression (doesn't trigger change handlers)
-userState.import(
-  { 
-    name: 'Jane Doe'
-  },
-  true // suppress hooks
-);
 ````
 
 ### Resetting State
@@ -181,6 +190,13 @@ userState.subscribe(
 );
 ````
 
+### Cleanup
+If you create short‑lived state instances, call `destroy()` to remove watchers and release references:
+
+````typescript
+userState.destroy();
+````
+
 ## Advanced Features
 ### Deep Object Watching
 When you modify nested properties, the system automatically detects these changes and triggers appropriate callbacks:
@@ -290,4 +306,4 @@ formState.state.password = 'securePassword123';
 document.getElementById('reset').addEventListener('click', () => {
   formState.reset();
 });
-````
+````

package/package.json

@@ -1,21 +1,20 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "3.0.0",
+  "version": "4.0.0-beta.10",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "exports": {
-    "./service/pagination": "./src/service/pagination/index.ts",
-    "./service/support": "./src/service/support/index.ts",
-    "./service/requests": "./src/service/requests/index.ts",
-    "./service/bulkRequests": "./src/service/bulkRequests/index.ts",
-    "./service/persistenceDrivers": "./src/service/persistenceDrivers/index.ts",
-    "./service/requests/exceptions": "./src/service/requests/exceptions/index.ts",
-    "./service/laravel/requests": "./src/service/laravel/requests/index.ts",
-    "./service/laravel/pagination": "./src/service/laravel/pagination/index.ts",
-    "./helpers": "./src/helpers.ts",
+    "./pagination": "./src/pagination/index.ts",
+    "./support": "./src/support/index.ts",
+    "./requests": "./src/requests/index.ts",
+    "./bulkRequests": "./src/bulkRequests/index.ts",
+    "./persistenceDrivers": "./src/persistenceDrivers/index.ts",
+    "./requests/exceptions": "./src/requests/exceptions/index.ts",
+    "./laravel/requests": "./src/laravel/requests/index.ts",
+    "./laravel/pagination": "./src/laravel/pagination/index.ts",
     "./vue": "./src/vue/index.ts",
     "./vue/forms": "./src/vue/forms/index.ts",
     "./vue/forms/validation": "./src/vue/forms/validation/index.ts",
@@ -75,8 +74,8 @@
     "vue-router": "^4.3.2"
   },
   "dependencies": {
-    "lodash-es": "^4.17.21",
-    "qs": "^6.12.0",
-    "uuid": "^11.1.0"
+    "lodash-es": "^4.17.23",
+    "qs": "^6.15.0",
+    "uuid": "^13.0.0"
   }
 }

package/release-tool.json

@@ -1,7 +1,26 @@
 {
   "version_file": "package.json",
-  "version_pattern": "\"version\":\\s*\"([0-9]+\\.[0-9]+\\.[0-9]+)\"",
+  "version_pattern": "\"version\":\\s*\"([0-9]+\\.[0-9]+\\.[0-9]+(?:-[a-z]+\\.[0-9]+)?)\"",
   "version_template": "\"version\": \"{}\"",
   "develop_branch": "develop",
-  "main_branch": "main"
-}
+  "main_branch": "main",
+  "docs": {
+    "build": {
+      "cwd": "./docs",
+      "commands": [
+        ["npm", "ci"],
+        ["npm", "run", "docs:build"]
+      ],
+      "output_dir": ".vitepress/dist"
+    },
+    "publish": {
+      "repo_path": "./docs",
+      "remote": "origin",
+      "branch": "gh-pages",
+      "subdir": "",
+      "commit_message": "docs: publish {tag}",
+      "add_nojekyll": true,
+      "force_push": false
+    }
+  }
+}

package/src/{service/bulkRequests → bulkRequests}/BulkRequestSender.ts

@@ -1,26 +1,30 @@
 import { BulkRequestWrapper } from './BulkRequestWrapper'
 import { BulkRequestEventEnum } from './BulkRequestEvent.enum'
-import { BaseRequest } from '../requests'
 
 export enum BulkRequestExecutionMode {
   PARALLEL = 'parallel',
   SEQUENTIAL = 'sequential'
 }
 
-export class BulkRequestSender {
-  // @ts-expect-error
-  protected events: Map<BulkRequestEventEnum, ((req: BulkRequestWrapper<BaseRequest>) => void)[]> = new Map()
+export class BulkRequestSender<
+  RequestLoaderLoadingType = unknown,
+  RequestBodyInterface = unknown,
+  ResponseClass = unknown,
+  RequestParamsInterface extends object = object
+> {
+  protected events: Map<
+    BulkRequestEventEnum,
+    ((req: BulkRequestWrapper<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface>) => void)[]
+  > = new Map()
   protected abortController: AbortController | undefined = undefined
 
   public constructor(
-    // @ts-expect-error
-    protected requests: BulkRequestWrapper<BaseRequest>[] = [],
+    protected requests: BulkRequestWrapper<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface>[] = [],
     protected executionMode: BulkRequestExecutionMode = BulkRequestExecutionMode.PARALLEL,
     protected retryCount: number = 0
   ) {}
 
-  // @ts-expect-error
-  public setRequests(requests: BulkRequestWrapper<BaseRequest>[] = []) {
+  public setRequests(requests: BulkRequestWrapper<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface>[] = []) {
     this.requests = requests
 
     return this
@@ -39,11 +43,13 @@ export class BulkRequestSender {
   }
 
   public get isLoading(): boolean {
-    return this.requests.some((req) => req.isLoading())
+    return this.requests.some((req) => Boolean(req.isLoading() as unknown))
   }
 
-  // @ts-expect-error
-  public on(event: BulkRequestEventEnum, callback: (req: BulkRequestWrapper<BaseRequest>) => void): this {
+  public on(
+    event: BulkRequestEventEnum,
+    callback: (req: BulkRequestWrapper<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface>) => void
+  ): this {
     if (!this.events.has(event)) {
       this.events.set(event, [])
     }
@@ -59,8 +65,10 @@ export class BulkRequestSender {
     return this
   }
 
-  // @ts-expect-error
-  protected emit(event: BulkRequestEventEnum, req: BulkRequestWrapper<BaseRequest>): void {
+  protected emit(
+    event: BulkRequestEventEnum,
+    req: BulkRequestWrapper<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface>
+  ): void {
     const callbacks = this.events.get(event) || []
 
     callbacks.forEach((callback) => callback(req))
@@ -89,10 +97,14 @@ export class BulkRequestSender {
     }
 
     return {
-      getSuccessCount: () => this.requests.filter((r) => !r.getError()).length,
-      getErrorCount: () => this.requests.filter((r) => r.getError()).length,
-      getSuccessfulResponses: () => this.requests.filter((r) => !r.getError()).map((r) => r.getResponse()),
-      getFailedResponses: () => this.requests.filter((r) => r.getError()).map((r) => r.getError())
+      getSuccessCount: () => this.requests.filter((r) => !r.hasError()).length,
+      getErrorCount: () => this.requests.filter((r) => r.hasError()).length,
+      getSuccessfulResponses: () =>
+        this.requests
+          .filter((r) => !r.hasError())
+          .map((r) => r.getResponse())
+          .filter((response): response is ResponseClass => response !== null),
+      getFailedResponses: () => this.requests.filter((r) => r.hasError()).map((r) => r.getError())
     }
   }