@tanglemedia/svelte-starter-toolbelt 2.0.0-next.2 → 2.0.0-next.3

package/README.md

@@ -1,58 +1,63 @@
-# Svelte library
+# @tanglemedia/svelte-starter-toolbelt
 
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+Shared service, query, mutation, proxy, and utility helpers used across the Svelte Starter.
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+## Service providers
 
-## Creating a project
+`createServiceFactory` builds typed collection services on top of a provider:
 
-If you're seeing this, you've probably already done this step. Congrats!
+- `createDirectusServiceProvider` for Directus-backed collections
+- `createFetchServiceProvider` for generic REST APIs
+- `createFixtureServiceProvider` for local JSON fixtures served through core's `fixture` adapter
 
-```bash
-# create a new project in the current directory
-npx sv create
+### Fixture provider example
 
-# create a new project in my-app
-npx sv create my-app
-```
+```typescript
+import {
+  createFixtureServiceProvider,
+  createServiceFactory
+} from '@tanglemedia/svelte-starter-toolbelt';
+import configuredApp from '$boot';
 
-## Developing
+type User = {
+  id: number;
+  name: string;
+};
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+type Schema = {
+  users: User;
+};
 
-```bash
-npm run dev
+export const createService = createServiceFactory<Schema, typeof createFixtureServiceProvider>(
+  configuredApp,
+  createFixtureServiceProvider
+);
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+export const usersService = createService('users');
+export const { findUsers, findUsersById } = usersService;
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
-
-## Building
+`createFixtureServiceProvider` defaults `adapterKey` to `'fixture'`, so it works with this
+`api.yml` setup:
 
-To build your library:
+```yaml
+default: 'fixture'
 
-```bash
-npm run package
+adapters:
+  fixture:
+    adapter: fixture
+    configuration: {}
 ```
 
-To create a production version of your showcase app:
+If you need a different adapter key:
 
-```bash
-npm run build
+```typescript
+export const tenantUsersService = createService('users', {
+  adapterKey: 'tenant-fixture'
+});
 ```
 
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
-
-## Publishing
+## More docs
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
-
-To publish your library to [npm](https://www.npmjs.com):
-
-```bash
-npm publish
-```
+- Package docs: `docs/packages/toolbelt.md`
+- Service-focused guide: `docs/packages/toolbelt-services.md`

package/dist/service/index.d.ts

@@ -1,3 +1,4 @@
 export * from './provider/create-directus-service.provider.ts';
 export * from './provider/create-fetch-service.provider.ts';
+export * from './provider/create-fixture-service.provider.ts';
 export * from './service.factory.ts';

package/dist/service/index.js

@@ -1,3 +1,4 @@
 export * from "./provider/create-directus-service.provider.js";
 export * from "./provider/create-fetch-service.provider.js";
+export * from "./provider/create-fixture-service.provider.js";
 export * from "./service.factory.js";

package/dist/service/provider/create-fixture-service.provider.d.ts

@@ -0,0 +1,9 @@
+import { ServiceAbstract, type AnyObject, type ConfigurableServiceClass, type ConfiguredApplication, type ServiceAbstractOptions } from '@tanglemedia/svelte-starter-core';
+export declare class BaseFixtureService<T extends AnyObject> extends ServiceAbstract<T> {
+}
+type FixtureServiceProviderOpt<T extends AnyObject> = {
+    serviceClass?: (base: ConfigurableServiceClass<T, BaseFixtureService<T>>) => ConfigurableServiceClass<T, BaseFixtureService<T>>;
+    adapterKey?: string;
+};
+export declare function createFixtureServiceProvider({ configureService }: ConfiguredApplication): <T extends AnyObject>(collection: string, opt?: Partial<ServiceAbstractOptions> & FixtureServiceProviderOpt<T>) => BaseFixtureService<T>;
+export {};

package/dist/service/provider/create-fixture-service.provider.js

@@ -0,0 +1,18 @@
+import { ServiceAbstract } from '@tanglemedia/svelte-starter-core';
+export class BaseFixtureService extends ServiceAbstract {
+}
+export function createFixtureServiceProvider({ configureService }) {
+    const services = {};
+    return (collection, opt) => {
+        const k = JSON.stringify([collection, opt]);
+        if (services[k]) {
+            return services[k];
+        }
+        const Service = opt?.serviceClass ? opt.serviceClass(BaseFixtureService) : BaseFixtureService;
+        return (services[k] = configureService(Service, {
+            path: collection,
+            adapterKey: opt?.adapterKey ?? 'fixture',
+            ...(opt ?? {})
+        }));
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanglemedia/svelte-starter-toolbelt",
-  "version": "2.0.0-next.2",
+  "version": "2.0.0-next.3",
   "files": [
     "src",
     "dist",
@@ -29,7 +29,7 @@
   },
   "peerDependencies": {
     "@directus/sdk": ">=17.0.0",
-    "@tanglemedia/svelte-starter-core": ">=4.0.0-next.0",
+    "@tanglemedia/svelte-starter-core": ">=4.0.0-next.1",
     "@tanstack/svelte-query": ">=6",
     "svelte": "^5.0.0"
   },
@@ -64,8 +64,8 @@
     "vite": "^8.0.8",
     "msw": "^2.12.7",
     "vitest": "^4.1.4",
-    "@tanglemedia/svelte-starter-types": "3.0.0-next.0",
-    "@tanglemedia/svelte-starter-core": "4.0.0-next.0"
+    "@tanglemedia/svelte-starter-core": "4.0.0-next.1",
+    "@tanglemedia/svelte-starter-types": "3.0.0-next.0"
   },
   "keywords": [
     "svelte"

package/src/lib/service/index.ts

@@ -1,3 +1,4 @@
 export * from './provider/create-directus-service.provider.ts';
 export * from './provider/create-fetch-service.provider.ts';
+export * from './provider/create-fixture-service.provider.ts';
 export * from './service.factory.ts';

package/src/lib/service/provider/create-fixture-service.provider.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test, vi } from 'vitest';
+import type { ConfiguredApplication, ServiceAbstractOptions } from '@tanglemedia/svelte-starter-core';
+
+import {
+	BaseFixtureService,
+	createFixtureServiceProvider
+} from './create-fixture-service.provider';
+
+describe('createFixtureServiceProvider', () => {
+	test('returns a factory function', () => {
+		const app = {
+			configureService: vi.fn()
+		} as unknown as ConfiguredApplication;
+
+		const createService = createFixtureServiceProvider(app);
+
+		expect(typeof createService).toBe('function');
+	});
+
+	test('caches service instances for the same collection and options', () => {
+		const instance = { service: 'fixture' };
+		const app = {
+			configureService: vi.fn(() => instance)
+		} as unknown as ConfiguredApplication;
+		const createService = createFixtureServiceProvider(app);
+
+		const first = createService('users');
+		const second = createService('users');
+
+		expect(first).toBe(second);
+		expect(app.configureService).toHaveBeenCalledOnce();
+	});
+
+	test('defaults adapterKey to fixture', () => {
+		const configureService = vi.fn();
+		const app = {
+			configureService
+		} as unknown as ConfiguredApplication;
+		const createService = createFixtureServiceProvider(app);
+
+		createService('users');
+
+		expect(configureService).toHaveBeenCalledWith(
+			BaseFixtureService,
+			expect.objectContaining({
+				path: 'users',
+				adapterKey: 'fixture'
+			})
+		);
+	});
+
+	test('passes through a custom adapterKey when provided', () => {
+		const configureService = vi.fn();
+		const app = {
+			configureService
+		} as unknown as ConfiguredApplication;
+		const createService = createFixtureServiceProvider(app);
+
+		createService('users', {
+			adapterKey: 'tenant-fixture'
+		});
+
+		expect(configureService).toHaveBeenCalledWith(
+			BaseFixtureService,
+			expect.objectContaining({
+				adapterKey: 'tenant-fixture'
+			})
+		);
+	});
+
+	test('uses a custom serviceClass when provided', () => {
+		const configureService = vi.fn();
+		const app = {
+			configureService
+		} as unknown as ConfiguredApplication;
+		const createService = createFixtureServiceProvider(app);
+
+		class CustomFixtureService<T extends Record<string, unknown>> extends BaseFixtureService<T> {}
+
+		createService('users', {
+			serviceClass: () => CustomFixtureService,
+			throwError: false
+		} as Partial<ServiceAbstractOptions>);
+
+		expect(configureService).toHaveBeenCalledWith(
+			CustomFixtureService,
+			expect.objectContaining({
+				path: 'users',
+				adapterKey: 'fixture',
+				throwError: false
+			})
+		);
+	});
+});

package/src/lib/service/provider/create-fixture-service.provider.ts

@@ -0,0 +1,37 @@
+import {
+	ServiceAbstract,
+	type AnyObject,
+	type ConfigurableServiceClass,
+	type ConfiguredApplication,
+	type ServiceAbstractOptions
+} from '@tanglemedia/svelte-starter-core';
+
+export class BaseFixtureService<T extends AnyObject> extends ServiceAbstract<T> {}
+
+type FixtureServiceProviderOpt<T extends AnyObject> = {
+	serviceClass?: (base: ConfigurableServiceClass<T, BaseFixtureService<T>>) => ConfigurableServiceClass<T, BaseFixtureService<T>>;
+	adapterKey?: string;
+};
+
+export function createFixtureServiceProvider({ configureService }: ConfiguredApplication) {
+	const services: Record<string, unknown> = {};
+
+	return <T extends AnyObject>(
+		collection: string,
+		opt?: Partial<ServiceAbstractOptions> & FixtureServiceProviderOpt<T>
+	): BaseFixtureService<T> => {
+		const k = JSON.stringify([collection, opt]);
+
+		if (services[k]) {
+			return services[k] as BaseFixtureService<T>;
+		}
+
+		const Service = opt?.serviceClass ? opt.serviceClass(BaseFixtureService) : BaseFixtureService<T>;
+
+		return (services[k] = configureService<T, BaseFixtureService<T>>(Service, {
+			path: collection,
+			adapterKey: opt?.adapterKey ?? 'fixture',
+			...(opt ?? {})
+		})) as BaseFixtureService<T>;
+	};
+}