### Start Svelte Development Server

Source: https://github.com/shellicar/ecosystem/blob/main/examples/svelte-adapter-azure-functions/svelte-app/README.md

Run this command after installing dependencies to start the development server. The `--open` flag will automatically open the app in your browser.

```bash
npm run dev
```

```bash
npm run dev -- --open
```

--------------------------------

### Install @shellicar/cosmos-query-builder

Source: https://github.com/shellicar/ecosystem/blob/main/packages/cosmos-query-builder/README.md

Install the library using npm or pnpm.

```sh
npm i --save @shellicar/cosmos-query-builder
```

```sh
pnpm add @shellicar/cosmos-query-builder
```

--------------------------------

### Install Adapter

Source: https://github.com/shellicar/ecosystem/blob/main/packages/svelte-adapter-azure-functions/README.md

Install the adapter as a development dependency using pnpm.

```bash
pnpm add -D @shellicar/svelte-adapter-azure-functions
```

--------------------------------

### Quick Start: Create Winston Logger with App Insights

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Set up Application Insights and create a Winston logger using the `createWinstonLogger` factory function. This example logs a 'Hello World' message.

```typescript
import { createWinstonLogger, ApplicationInsightsVersion } from '@shellicar/winston-azure-application-insights';
import applicationinsights from 'applicationinsights';

applicationinsights.setup().start();

const logger = createWinstonLogger({
  insights: {
    version: ApplicationInsightsVersion.V3,
    client: applicationinsights.defaultClient
  },
});
logger.info('Hello World');
```

--------------------------------

### Factory Function Setup

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Demonstrates a simple setup using the factory function to create the Application Insights transport. Ensure Application Insights is set up and started before creating the transport.

```typescript
import applicationinsights from 'applicationinsights';
import { createApplicationInsightsTransport, ApplicationInsightsVersion } from '@shellicar/winston-azure-application-insights';

applicationinsights.setup().start();

const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V3,
  client: applicationinsights.defaultClient,
});
```

--------------------------------

### Install @shellicar/build-graphql

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-graphql/README.md

Install the package using npm or pnpm.

```sh
npm i --save @shellicar/build-graphql
```

```sh
pnpm add @shellicar/build-graphql
```

--------------------------------

### Install @shellicar/build-azure-local-settings with pnpm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-azure-local-settings/README.md

Install the package as a development dependency using pnpm.

```sh
pnpm add -D @shellicar/build-azure-local-settings
```

--------------------------------

### Quick Start: Register and Resolve Services

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Demonstrates basic service registration and resolution using createServiceCollection, register, buildProvider, and resolve.

```typescript
import { createServiceCollection } from '@shellicar/core-di';
abstract class IAbstract {}
class Concrete implements IAbstract {}
const services = createServiceCollection();
services.register(IAbstract).to(Concrete);
const provider = services.buildProvider();
const svc = provider.resolve(IAbstract);
```

--------------------------------

### Comprehensive Usage Example

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

A complete example demonstrating dependency definition with decorators, service module registration, scope creation, and service resolution.

```typescript
import { dependsOn, createServiceCollection, IServiceModule, type IServiceCollection } from '@shellicar/core-di';

// Define the dependency interface
abstract class IClock {
  abstract now(): Date;
}
// And implementation
class DefaultClock implements IClock {
  now(): Date {
    return new Date();
  }
}

// Define your interface
abstract class IDatePrinter {
  abstract handle(): string;
}
// And implementation
class DatePrinter implements IDatePrinter {
  @dependsOn(IClock) public readonly clock!: IClock;

  handle(): string {
    return `The time is: ${this.clock.now().toISOString()}`;
  }  
}

class TimeModule extends IServiceModule {
  public registerServices(services: IServiceCollection): void {
    services.register(IClock).to(DefaultClock).singleton();
    services.register(IDatePrinter).to(DatePrinter).scoped();
  }
}

// Register and build provider
const services = createServiceCollection();
services.registerModules([TimeModule]);
const sp = services.buildProvider();

// Optionally create a scope
using scope = sp.createScope();

// Resolve the interface
const svc = scope.resolve(IDatePrinter);
console.log(svc.handle());
```

--------------------------------

### Install @shellicar/build-azure-local-settings with npm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-azure-local-settings/README.md

Install the package as a development dependency using npm.

```sh
npm i --save-dev @shellicar/build-azure-local-settings
```

--------------------------------

### Quick Start with @shellicar/core-config

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Demonstrates creating a factory and using it to securely handle string, connection string, and URL values.

```ts
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();

console.log(factory.string('myPassword123'));
console.log(factory.connectionString('Server=myserver.uri;Password=myPassword123'));
console.log(factory.url(new URL('http://myuser:myPassword123@myserver.uri')));
```

--------------------------------

### Install @shellicar/core-config with pnpm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Use this command to install the library using pnpm.

```sh
pnpm add @shellicar/core-config
```

--------------------------------

### Install @shellicar/core-di with npm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Use npm to install the core-di package.

```sh
npm i --save @shellicar/core-di
```

--------------------------------

### Install @shellicar/core-config with npm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Use this command to install the library using npm.

```sh
npm i --save @shellicar/core-config
```

--------------------------------

### Install @shellicar/build-version

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-version/README.md

Install the package using npm or pnpm.

```sh
npm i --save @shellicar/build-version
```

```sh
pnpm add @shellicar/build-version
```

--------------------------------

### Install @shellicar/core-di with pnpm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Use pnpm to install the core-di package.

```sh
pnpm add @shellicar/core-di
```

--------------------------------

### Install @shellicar/graphql-codegen-treeshake

Source: https://github.com/shellicar/ecosystem/blob/main/packages/graphql-codegen-treeshake/README.md

Install the package as a development dependency using pnpm.

```sh
pnpm add -D @shellicar/graphql-codegen-treeshake
```

--------------------------------

### Azure local.settings.json Example

Source: https://context7.com/shellicar/ecosystem/llms.txt

Example configuration file for Azure local settings. It includes non-encrypted values and references to Azure Key Vault secrets.

```json
{
  "IsEncrypted": false,
  "Values": {
    "GREETING_MESSAGE": "Hello from local settings",
    "DB_CONNECTION": "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/db-conn/)"
  }
}
```

--------------------------------

### Full Usage Example with Cosmos DB Container

Source: https://github.com/shellicar/ecosystem/blob/main/packages/cosmos-query-builder/README.md

Demonstrates initializing the query builder with a specific type and executing a query against a Cosmos DB container.

```typescript
import { createCosmosQueryBuilder, SortDirection } from '@shellicar/cosmos-query-builder';
import type { Container } from '@azure/cosmos';

type Person = {
  id: string;
  type: 'Person';
  age: number;
  created: string;
  name: {
    givenName: string;
    familyName: string;
  };
};

const queryPeople = async (container: Container) => {
  const builder = createCosmosQueryBuilder<Person>();
  
  builder.where('type', 'eq', 'Person');
  builder.where('age', 'gt', 18);
  builder.orderBy('created', SortDirection.Desc);
  builder.limit(50);
  
  const results = await builder.getAll(container);
  console.log(`Found ${results.count} people`);
  
  return results.items;
};
```

--------------------------------

### Install @shellicar/build-clean with npm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Install the build-clean plugin as a development dependency using npm.

```sh
npm i --save-dev @shellicar/build-clean
```

--------------------------------

### Install @shellicar/build-clean with pnpm

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Install the build-clean plugin as a development dependency using pnpm.

```sh
pnpm add -D @shellicar/build-clean
```

--------------------------------

### Handle Connection Strings with Core Config

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Shows how to secure connection strings using factory.connectionString(). Includes an example of specifying custom keys to be secured.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const conn = factory.connectionString('Server=myserver;Password=myPassword123');
console.log(conn.toString());
// Server=myserver;Password=sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

// Custom secret keys
console.log(factory.connectionString('Server=myserver;SuperSecretKey=myPassword123', ['SuperSecretKey']));
// {
//   Server: 'myserver',
//   SuperSecretKey: 'sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716'
// }
```

--------------------------------

### Real World Example with Zod for Environment Validation

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Shows how to integrate core-config with Zod for validating and securing environment variables. It demonstrates transforming URLs, API keys, and SQL connection strings into their secure types.

```typescript
import { env } from 'node:process';
import { createFactory } from '@shellicar/core-config';
import { z } from 'zod';

const factory = createFactory();

const envSchema = z.object({
  // MongoDB connection string with username/password
  MONGODB_URL: z.url().transform((x) => factory.url(new URL(x))),

  // API key for external service
  API_KEY: z
    .string()
    .min(1)
    .transform((x) => factory.string(x)),

  // SQL Server connection string
  SQL_CONNECTION: z.string().transform((x) => factory.connectionString(x)),
});

// Parse environment variables
const config = envSchema.parse(env);

// Values are now strongly typed and secured
console.log(config.MONGODB_URL.toString());
// mongodb://myuser:sha256%3A...@mongodb.example.com/

console.log(config.API_KEY.toString());
// sha256:...

console.log(config.SQL_CONNECTION.toString());
// Server=myserver;Database=mydb;User Id=admin;Password=sha256:...
```

--------------------------------

### Install Winston Azure Application Insights

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Install the package using pnpm. This command adds the necessary dependency to your project.

```sh
pnpm add @shellicar/winston-azure-application-insights
```

--------------------------------

### Complete Logger Setup with Console and App Insights

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Illustrates how to create a Winston logger instance that includes both console output and the Application Insights transport. This setup allows for simultaneous logging to the console and Azure.

```typescript
import { createWinstonLogger, ApplicationInsightsVersion } from '@shellicar/winston-azure-application-insights';
import applicationinsights from 'applicationinsights';

const logger = createWinstonLogger({
  winston: {
    console: {
      enabled: true,
      format: {
        output: 'json',
        timestamp: true,
        errors: true,
        colorize: true,
      },
    },
    defaults: {
      level: 'info',
    },
  },
  insights: {
    version: ApplicationInsightsVersion.V3,
    client: applicationinsights.defaultClient,
  },
});

logger.info('Application started');
```

--------------------------------

### Main Application Entry Point with Process Environment Variables

Source: https://context7.com/shellicar/ecosystem/llms.txt

Example of a main application module that accesses configuration values injected via `process.env` by the Azure local settings build plugin. Key Vault references are resolved before this code executes.

```typescript
export default async () => {
  console.log('Greeting:', process.env.GREETING_MESSAGE);
  console.log('DB:', process.env.DB_CONNECTION);
};
```

--------------------------------

### Handle Strings with HMAC Secret

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Illustrates creating a secure string when a secret is provided to the factory, enabling HMAC hashing. The output is similar to the basic string example.

```ts
import { createFactory } from '@shellicar/core-config';

const factory = createFactory({ secret: 'mySecret' });
const secret = factory.string('myPassword123');

console.log(secret.toString()); 
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

console.log(JSON.stringify({ secret }));
// {"secret":"sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716"}
```

--------------------------------

### Use Existing Application Insights Client

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

When Application Insights is already loaded in your environment, use the existing default client instead of calling setup().

```typescript
import applicationinsights from 'applicationinsights';
const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V3,
  client: applicationinsights.defaultClient,
});
```

--------------------------------

### Type-Safe Registration

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Register a service with its implementation, ensuring type safety. The example shows an error when trying to register an abstract class directly.

```typescript
const services = createServiceCollection();
abstract class IAbstract { abstract method(): void; }
abstract class Concrete {}
services.register(IAbstract).to(Concrete);
//                              ^ Error
```

--------------------------------

### Filtering Traces and Exceptions

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Provides examples of using `traceFilter` and `exceptionFilter` to selectively send telemetry data. These filters allow custom logic to decide which events should be transmitted to Application Insights.

```typescript
const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V3,
  client: defaultClient,
  traceFilter: (trace) => trace.severity !== KnownSeverityLevel.Verbose,
  exceptionFilter: (exception) => !exception.exception.message.includes('ignore'),
});
```

--------------------------------

### Basic Query Construction with @shellicar/cosmos-query-builder

Source: https://github.com/shellicar/ecosystem/blob/main/packages/cosmos-query-builder/README.md

Demonstrates creating a query builder instance, adding filters and sorting, and executing the query.

```ts
import { createCosmosQueryBuilder, SortDirection } from '@shellicar/cosmos-query-builder';

const builder = createCosmosQueryBuilder<Person>();

builder.where('type', 'eq', 'Person');
builder.where('age', 'gt', 18);
builder.orderBy('created', SortDirection.Desc);
builder.limit(50);

const results = await builder.getAll(container);
```

--------------------------------

### Override Lifetime for Testing

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Override the default lifetime of a registered service, for example, to change a singleton to transient for testing scenarios. This example also demonstrates setting logging options.

```typescript
const services = createServiceCollection({ logLevel: LogLevel.Debug });
services.register(IAbstract).to(Concrete).singleton();
const provider = services.buildProvider();
provider.Services.overrideLifetime(IAbstract, Lifetime.Transient);
provider.resolve(IAbstract) !== provider.resolve(IAbstract);
```

--------------------------------

### Create and Configure Service Collection with Dependency Injection

Source: https://context7.com/shellicar/ecosystem/llms.txt

Demonstrates setting up a dependency injection container using `createServiceCollection`. Supports singletons, scoped, and transient lifetimes, service modules, factory functions, and multiple registrations. Use for managing dependencies and enabling testability.

```typescript
import {
  createServiceCollection,
  dependsOn,
  IServiceModule,
  ResolveMultipleMode,
  Lifetime,
  LogLevel,
  type IServiceCollection,
} from '@shellicar/core-di';

abstract class IClock { abstract now(): Date; }
class DefaultClock implements IClock { now() { return new Date(); } }

abstract class IGreeter { abstract greet(): string; }
class Greeter implements IGreeter {
  @dependsOn(IClock) private readonly clock!: IClock;
  greet() { return `Hello at ${this.clock.now().toISOString()}`;
}

class AppModule extends IServiceModule {
  registerServices(services: IServiceCollection) {
    services.register(IClock).to(DefaultClock).singleton();
    services.register(IGreeter).to(Greeter).scoped();
  }
}

const services = createServiceCollection();
services.registerModules([AppModule]);
const provider = services.buildProvider();

using scope = provider.createScope();
const greeter = scope.resolve(IGreeter);
console.log(greeter.greet());

abstract class IRedisOptions { abstract port: number; abstract host: string; }
services.register(Redis).to(Redis, (container) => {
  const options = container.resolve(IRedisOptions);
  return new Redis({ port: options.port, host: options.host });
});

services.register(IAbstract1, IAbstract2).to(Concrete).singleton();

const testServices = createServiceCollection({ registrationMode: ResolveMultipleMode.LastRegistered });
testServices.register(IGreeter).to(Greeter);
testServices.register(IGreeter).to(MockGreeter);
const testProvider = testServices.buildProvider();
const mock = testProvider.resolve(IGreeter);

provider.Services.overrideLifetime(IClock, Lifetime.Transient);

const verboseServices = createServiceCollection({ logLevel: LogLevel.Debug });
```

--------------------------------

### Build Svelte Project for Production

Source: https://github.com/shellicar/ecosystem/blob/main/examples/svelte-adapter-azure-functions/svelte-app/README.md

Execute this command to create an optimized production build of your Svelte application.

```bash
npm run build
```

--------------------------------

### Create a New Svelte Project

Source: https://github.com/shellicar/ecosystem/blob/main/examples/svelte-adapter-azure-functions/svelte-app/README.md

Use these commands to create a new Svelte project. You can create it in the current directory or specify a project name.

```bash
npx sv create
```

```bash
npx sv create my-app
```

--------------------------------

### Configure tsup with @shellicar/build-azure-local-settings

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-azure-local-settings/README.md

Add the plugin to your tsup configuration to enable local settings loading.

```ts
// tsup.config.ts
import plugin from '@shellicar/build-azure-local-settings/esbuild';
import { defineConfig } from 'tsup';

export default defineConfig({
  esbuildPlugins: [
    plugin({
      mainModule: './src/main.ts',
    }),
  ],
});
```

--------------------------------

### Disabling Exception Tracking with Custom Logic

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Shows how to customize the error detection logic using the `isError` option. This allows you to define precisely what types of objects should be treated as exceptions, for example, only instances of a specific custom error class.

```typescript
const transport = createApplicationInsightsTransport({
  version: 3,
  client: defaultClient,
  // Custom function to determine what counts as an error
  isError: (obj) => obj instanceof CustomError,
});
```

--------------------------------

### Configure esbuild with @shellicar/build-azure-local-settings

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-azure-local-settings/README.md

Integrate the plugin into your esbuild build process. It loads local settings when the --watch flag is present.

```ts
// build.ts
import plugin from '@shellicar/build-azure-local-settings/esbuild';
import esbuild from 'esbuild';

const watch = process.argv.includes('--watch');

const ctx = await esbuild.context({
  outdir: 'dist',
  bundle: true,
  platform: 'node',
  format: 'esm',
  plugins: [
    plugin({
      mainModule: './src/main.ts',
      loadLocalSettings: watch,
    }),
  ],
});

if (watch) {
  await ctx.watch();
} else {
  await ctx.rebuild();
  ctx.dispose();
}
```

--------------------------------

### Configure esbuild Options

Source: https://github.com/shellicar/ecosystem/blob/main/packages/svelte-adapter-azure-functions/README.md

Customize esbuild options for the adapter, such as disabling minification.

```javascript
adapter({
  esbuildOptions: {
    minify: false
  }
})
```

--------------------------------

### Handle Strings with Core Config

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Demonstrates creating a secure string using the factory.string() method. The output shows the hashed representation and its JSON stringified form.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const secret = factory.string('myPassword123');

console.log(secret.toString()); 
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

console.log(JSON.stringify({ secret }));
// {"secret":"sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716"}
```

--------------------------------

### Import Version Information

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-version/README.md

Import the version information into your application's main entry point.

```typescript
// main.ts
import version from '@shellicar/build-version/version'
```

--------------------------------

### Configure GraphQLPlugin with Vite

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-graphql/README.md

Integrate the GraphQLPlugin into your Vite configuration file.

```ts
import GraphQLPlugin from '@shellicar/build-graphql/vite'

export default defineConfig({
  // other options
  plugins: [
    GraphQLPlugin({
      globPattern: 'src/**/*.graphql'
    })
  ],
});
```

--------------------------------

### Configure SvelteKit Adapter

Source: https://github.com/shellicar/ecosystem/blob/main/packages/svelte-adapter-azure-functions/README.md

Configure your svelte.config.js file to use the Azure Functions adapter.

```javascript
import adapter from '@shellicar/svelte-adapter-azure-functions';

export default {
  kit: {
    adapter: adapter()
  }
};
```

--------------------------------

### Vite Configuration with Build Clean Plugin

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Integrates the build-clean plugin into a Vite project. Ensure the plugin is imported correctly and configure options as needed.

```typescript
// vite.config.ts
import cleanPlugin from '@shellicar/build-clean/vite'

export default defineConfig({
  plugins: [cleanPlugin({ destructive: true })]
})
```

--------------------------------

### Default esbuild Options

Source: https://github.com/shellicar/ecosystem/blob/main/packages/svelte-adapter-azure-functions/README.md

View the default esbuild options used by the adapter. These options are defined in defaults.ts and include settings for bundling, platform, target, and format.

```typescript
export const defaults = {
  bundle: true,
  platform: 'node',
  target: 'node20',
  format: 'esm',
  // ...see defaults.ts for full options
};
```

--------------------------------

### Handle URLs with Passwords using Core Config

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-config/README.md

Demonstrates securing URLs that contain passwords using the factory.url() method. The output shows the secured URL and its structured representation.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const url = new URL('https://user:myPassword123@example.com?key=value');
const secureUrl = factory.url(url);

console.log(secureUrl.toString());
// https://user:sha256%3A71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716@example.com/?key=value

console.log(secureUrl);
// {
//   href: 'https://user@example.com/',
//   password: 'sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716',
//   searchParams: { key: 'value' }
// }
```

--------------------------------

### Configure GraphQL Code Generator

Source: https://github.com/shellicar/ecosystem/blob/main/packages/graphql-codegen-treeshake/README.md

Set up the codegen.ts configuration file to use the tree-shaking preset. Ensure your schema and documents are correctly specified.

```ts
import {
  preset
} from '@shellicar/graphql-codegen-treeshake';
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'src/**/*.graphql',
  documents: ['src/**/requests.ts'],
  generates: {
    'src/lib/graphql/': {
      preset,
      presetConfig: {
        fragmentMasking: false,
      },
    },
  },
};

export default config;
```

--------------------------------

### Configure esbuild with @shellicar/build-clean

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Integrate the build-clean plugin into your esbuild build process. Set 'destructive: true' to enable file deletion.

```ts
import cleanPlugin from '@shellicar/build-clean/esbuild'
import { build } from 'esbuild'

await build({
  entryPoints: ['src/main.ts'],
  outdir: 'dist',
  plugins: [
    cleanPlugin({
      // Required to actually delete files
      destructive: true
    })
  ]
})
```

--------------------------------

### Import GraphQL Typedefs

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-graphql/README.md

Import GraphQL typedefs from the virtual module provided by the plugin.

```ts
import typedefs from '@shellicar/build-graphql/typedefs'
```

--------------------------------

### Builder Pattern Methods

Source: https://github.com/shellicar/ecosystem/blob/main/packages/cosmos-query-builder/README.md

Use chained methods like `where()`, `orderBy()`, and `limit()` for constructing queries instead of raw SQL.

```typescript
builder.where('type', 'eq', 'Person');
builder.where('age', 'gt', 18);
builder.orderBy('created', SortDirection.Desc);
builder.limit(50);
```

--------------------------------

### Configure esbuild Plugin for Azure Local Settings

Source: https://context7.com/shellicar/ecosystem/llms.txt

Integrates `@shellicar/build-azure-local-settings` with esbuild to load `local.settings.json`. The plugin resolves Key Vault references and injects values into `process.env`. Configure `mainModule` and `loadLocalSettings`.

```typescript
import plugin from '@shellicar/build-azure-local-settings/esbuild';
import esbuild from 'esbuild';

const watch = process.argv.includes('--watch');

const ctx = await esbuild.context({
  outdir: 'dist',
  bundle: true,
  platform: 'node',
  format: 'esm',
  plugins: [
    plugin({
      mainModule: './src/main.ts',
      loadLocalSettings: watch, 
    }),
  ],
});

if (watch) {
  await ctx.watch();
} else {
  await ctx.rebuild();
  ctx.dispose();
}
```

--------------------------------

### Configure GraphQLPlugin with esbuild

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-graphql/README.md

Configure and use the GraphQLPlugin within your esbuild build process. Specify options like globPattern and debug.

```ts
import graphqlPlugin from '@shellicar/build-graphql/esbuild';
import type { Options } from '@shellicar/build-graphql/types';
import { build } from 'esbuild';

const options: Options = {
  globPattern: '../**/*.graphql',
  debug: true,
};

await build({
  entryPoints: ['src/main.ts'],
  outdir: 'dist',
  bundle: true,
  platform: 'node',
  target: 'node20',
  tsconfig: 'tsconfig.json',
  plugins: [graphqlPlugin(options)],
});
```

--------------------------------

### Configure SvelteKit Azure Functions Adapter

Source: https://context7.com/shellicar/ecosystem/llms.txt

Integrate SvelteKit with Azure Functions v4 using `@shellicar/svelte-adapter-azure-functions`. Configure esbuild options and set the function authentication level via the `SERVER_AUTH_LEVEL` environment variable.

```javascript
// svelte.config.js
import adapter from '@shellicar/svelte-adapter-azure-functions';

export default {
  kit: {
    adapter: adapter({
      esbuildOptions: {
        minify: true,
        // Additional esbuild options to merge with defaults:
        // bundle: true, platform: 'node', target: 'node20', format: 'esm'
      },
    }),
  },
};

// The adapter generates a single Azure Function equivalent to:
// app.http('server', {
//   handler,
//   authLevel: getAuthLevel(process.env.SERVER_AUTH_LEVEL), // 'anonymous' | 'function' | 'admin'
//   route: '{*url}',
//   methods: ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'],
// });

// Set auth level via environment variable (defaults to 'anonymous'):
// SERVER_AUTH_LEVEL=function
```

--------------------------------

### Version Metadata Plugin for Vite/esbuild

Source: https://context7.com/shellicar/ecosystem/llms.txt

Calculates build version information and exposes it as a virtual module. Supports custom version calculators via the `versionCalculator` option.

```typescript
// vite.config.ts
import VersionPlugin from '@shellicar/build-version/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [VersionPlugin({})],
});

// esbuild — build.ts
import VersionPlugin from '@shellicar/build-version/esbuild';
import { build } from 'esbuild';

await build({
  entryPoints: ['src/main.ts'],
  outdir: 'dist',
  plugins: [VersionPlugin({})],
});

// Custom version calculator
VersionPlugin({ versionCalculator: () => '1.0.0-custom' });

// src/main.ts — consume the virtual module
import version from '@shellicar/build-version/version';

// VersionInfo shape:
// {
//   buildDate: string;   // ISO date of build
//   branch: string;      // git branch
//   sha: string;         // full commit SHA
//   shortSha: string;    // short commit SHA
//   commitDate: string;  // ISO date of commit
//   version: string;     // e.g. "1.2.4" or "1.2.3-feature-name.2"
// }
console.log(version.version);    // "1.2.4"
console.log(version.branch);     // "main"
console.log(version.buildDate);  // "2024-06-01T12:00:00.000Z"
```

--------------------------------

### Log Version Information

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-version/README.md

Log the imported version information to the console.

```typescript
import version from '@shellicar/build-version/version'

console.log(version)
```

--------------------------------

### Configure Vite with VersionPlugin

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-version/README.md

Integrate the VersionPlugin into your Vite configuration to enable version calculation.

```typescript
// vite.config.ts
import VersionPlugin from '@shellicar/build-version/vite'

export default defineConfig({
  plugins: [
    VersionPlugin({})
  ]
})
```

--------------------------------

### GraphQL File Loader Plugin for esbuild/Vite

Source: https://context7.com/shellicar/ecosystem/llms.txt

Scans `.graphql` files matching a glob pattern and exposes them as a virtual module. Configure with `globPattern` and optional `debug` flag.

```typescript
// esbuild — build.ts
import graphqlPlugin from '@shellicar/build-graphql/esbuild';
import { build } from 'esbuild';

await build({
  entryPoints: ['src/main.ts'],
  outdir: 'dist',
  bundle: true,
  platform: 'node',
  target: 'node20',
  plugins: [
    graphqlPlugin({
      globPattern: 'src/**/*.graphql',
      debug: true,
    }),
  ],
});

// vite.config.ts
import GraphQLPlugin from '@shellicar/build-graphql/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    GraphQLPlugin({ globPattern: 'src/**/*.graphql' }),
  ],
});

// src/main.ts — consume the virtual module
import typedefs from '@shellicar/build-graphql/typedefs';
// typedefs is the merged DocumentNode from all matched .graphql files
import { ApolloServer } from '@apollo/server';
const server = new ApolloServer({ typeDefs: typedefs });
```

--------------------------------

### Build Clean Plugin Options Interface

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Defines the available options for configuring the build-clean plugin. Use `destructive: true` to enable actual file deletion.

```typescript
interface Options {
  /** Show detailed debug information */
  debug?: boolean
  
  /** Show verbose file-by-file processing */
  verbose?: boolean
  
  /** Actually delete files (default: false for safety) */
  destructive?: boolean
}
```

--------------------------------

### Configure tsup with @shellicar/build-clean

Source: https://github.com/shellicar/ecosystem/blob/main/packages/build-clean/README.md

Integrate the build-clean plugin into your tsup configuration. Ensure tsup's native clean option is disabled. Set 'destructive: true' to enable file deletion and 'verbose: true' for detailed output.

```ts
// tsup.config.ts
import cleanPlugin from '@shellicar/build-clean/esbuild'
import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts'],
  // Important: disable tsup's clean
  clean: false,
  esbuildPlugins: [
    cleanPlugin({
      destructive: true,
      verbose: true
    })
  ]
})
```

--------------------------------

### Configure tsup Plugin for Azure Local Settings

Source: https://context7.com/shellicar/ecosystem/llms.txt

Integrates `@shellicar/build-azure-local-settings` with tsup. The plugin resolves Key Vault references from `local.settings.json` and injects them into `process.env`. Set `loadLocalSettings` to `true` to enable.

```typescript
import plugin from '@shellicar/build-azure-local-settings/esbuild';
import { defineConfig } from 'tsup';

export default defineConfig({
  esbuildPlugins: [
    plugin({
      mainModule: './src/main.ts',
      loadLocalSettings: true,
    }),
  ],
});
```

--------------------------------

### createFactory() — Secure configuration value factory

Source: https://context7.com/shellicar/ecosystem/llms.txt

Creates a factory that wraps sensitive strings, connection strings, and URLs, automatically hashing them for serialization and logging. The raw secret value remains accessible via `.secretValue`.

```APIDOC
## createFactory()

### Description
Creates a factory that wraps sensitive strings, connection strings, and URLs so they are automatically SHA-256-hashed whenever they are serialised, logged, or converted to strings. The raw secret value is still accessible via the `.secretValue` property when explicitly needed.

### Usage
```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const secret = factory.string('myPassword123');
console.log(secret.toString());
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

const conn = factory.connectionString('Server=myserver;Password=myPassword123');
console.log(conn.toString());
// Server=myserver;Password=sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

const url = factory.url(new URL('https://user:myPassword123@example.com?key=value'));
console.log(url.toString());
// https://user:sha256%3A...@example.com/?key=value

// HMAC mode
const hmacFactory = createFactory({ secret: 'myHmacSecret' });
const hmacSecret = hmacFactory.string('myPassword123');
console.log(hmacSecret.toString()); // sha256:<hmac-hash>

// Integration with Zod
import { z } from 'zod';
import { env } from 'node:process';

const envSchema = z.object({
  MONGODB_URL: z.string().url().transform((x) => factory.url(new URL(x))),
  API_KEY: z.string().min(1).transform((x) => factory.string(x)),
  SQL_CONNECTION: z.string().transform((x) => factory.connectionString(x)),
});

const config = envSchema.parse(env);
console.log(config.API_KEY.toString()); // sha256:...
console.log(config.SQL_CONNECTION.toString()); // Server=...;Password=sha256:...
```
```

--------------------------------

### Tree-shaking Preset for @graphql-codegen/client-preset

Source: https://context7.com/shellicar/ecosystem/llms.txt

A drop-in replacement preset for `@graphql-codegen/client-preset` that generates only TypeScript types reachable from actual operations and fragments, eliminating unused schema types.

```typescript
// codegen.ts
import { preset } from '@shellicar/graphql-codegen-treeshake';
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'src/**/*.graphql',
  documents: ['src/**/requests.ts'],
  generates: {
    'src/lib/graphql/': {
      preset,
      presetConfig: {
        fragmentMasking: false,
      },
    },
  },
};

export default config;

// Run codegen
// npx graphql-codegen --config codegen.ts
//
// Result: only types used by operations in src/**/requests.ts
// are emitted — unused schema types are excluded.
```

--------------------------------

### Create Winston Logger with Application Insights Transport

Source: https://context7.com/shellicar/ecosystem/llms.txt

Initializes a Winston logger that includes both console output (for development) and an Application Insights transport. Ensure Application Insights connection string is set in environment variables.

```typescript
import applicationinsights from 'applicationinsights';
import {
  createWinstonLogger,
  createApplicationInsightsTransport,
  ApplicationInsightsVersion,
  TelemetrySeverity,
  KnownSeverityLevel,
} from '@shellicar/winston-azure-application-insights';

applicationinsights.setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING).start();

// --- Full logger with console + Application Insights ---
const logger = createWinstonLogger({
  winston: {
    console: {
      enabled: process.env.NODE_ENV !== 'production',
      format: { output: 'json', timestamp: true, errors: true, colorize: true },
    },
    defaults: { level: 'info' },
  },
  insights: {
    version: ApplicationInsightsVersion.V3,
    client: applicationinsights.defaultClient,
  },
});

logger.info('Application started');
logger.warn('Low memory', { threshold: '80%', current: '85%' });

// --- Error extraction behaviour ---
logger.error('Plain string error');                         // → trace only
logger.error(new Error('DB connection failed'));            // → exception only (no trace)
logger.error('Operation failed', new Error('Timeout'));     // → trace + exception
logger.error('Multiple failures', new Error('DB'), new Error('Cache')); // → trace + 2 exceptions

// --- Properties from splat parameters ---
logger.info('User action', { userId: 42, action: 'login' }); // properties attached to trace
```

--------------------------------

### Factory Method Instantiation

Source: https://github.com/shellicar/ecosystem/blob/main/packages/core-di/README.md

Provide a factory function for creating service instances, allowing custom instantiation logic that can resolve other dependencies.

```typescript
services.register(Redis).to(Redis, x => {
  const options = x.resolve(IRedisOptions);
  return new Redis({
    port: options.port,
    host: options.host,
  });
});
```

--------------------------------

### @shellicar/svelte-adapter-azure-functions

Source: https://context7.com/shellicar/ecosystem/llms.txt

SvelteKit adapter for Azure Functions v4. Builds a SvelteKit application into a single Azure Function (HTTP trigger, all methods, catch-all route) using esbuild.

```APIDOC
## `@shellicar/svelte-adapter-azure-functions`

### Description
SvelteKit adapter for Azure Functions v4. Builds a SvelteKit application into a single Azure Function (HTTP trigger, all methods, catch-all route) using esbuild. Supports configurable esbuild options and function auth level via environment variable.

### Configuration
```typescript
// svelte.config.js
import adapter from '@shellicar/svelte-adapter-azure-functions';

export default {
  kit: {
    adapter: adapter({
      esbuildOptions: {
        minify: true,
        // Additional esbuild options to merge with defaults:
        // bundle: true, platform: 'node', target: 'node20', format: 'esm'
      },
    }),
  },
};

// The adapter generates a single Azure Function equivalent to:
// app.http('server', {
//   handler,
//   authLevel: getAuthLevel(process.env.SERVER_AUTH_LEVEL), // 'anonymous' | 'function' | 'admin'
//   route: '{*url}',
//   methods: ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'],
// });

// Set auth level via environment variable (defaults to 'anonymous'):
// SERVER_AUTH_LEVEL=function
```
```

--------------------------------

### createWinstonLogger and createApplicationInsightsTransport

Source: https://context7.com/shellicar/ecosystem/llms.txt

These functions allow you to create a Winston logger with an Application Insights transport or a standalone transport. They support various configurations for SDK versions, severity mapping, and filtering.

```APIDOC
## `createWinstonLogger()` / `createApplicationInsightsTransport()` — Winston transport for Azure Application Insights

Creates a Winston logger or standalone transport that sends traces and exceptions to Azure Application Insights. Supports SDK v2 and v3, automatic Error extraction, custom severity mapping, trace/exception filtering, and local console logging for development.

```typescript
import applicationinsights from 'applicationinsights';
import {
  createWinstonLogger,
  createApplicationInsightsTransport,
  ApplicationInsightsVersion,
  TelemetrySeverity,
  KnownSeverityLevel,
} from '@shellicar/winston-azure-application-insights';

applicationinsights.setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING).start();

// --- Full logger with console + Application Insights ---
const logger = createWinstonLogger({
  winston: {
    console: {
      enabled: process.env.NODE_ENV !== 'production',
      format: { output: 'json', timestamp: true, errors: true, colorize: true },
    },
    defaults: { level: 'info' },
  },
  insights: {
    version: ApplicationInsightsVersion.V3,
    client: applicationinsights.defaultClient,
  },
});

logger.info('Application started');
logger.warn('Low memory', { threshold: '80%', current: '85%' });

// --- Error extraction behaviour ---
logger.error('Plain string error');                         // → trace only
logger.error(new Error('DB connection failed'));            // → exception only (no trace)
logger.error('Operation failed', new Error('Timeout'));     // → trace + exception
logger.error('Multiple failures', new Error('DB'), new Error('Cache')); // → trace + 2 exceptions

// --- Properties from splat parameters ---
logger.info('User action', { userId: 42, action: 'login' }); // properties attached to trace

// --- Standalone transport with filtering ---
const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V3,
  client: applicationinsights.defaultClient,
  severityMapping: {
    error: TelemetrySeverity.Error,
    warn: TelemetrySeverity.Warning,
    info: TelemetrySeverity.Information,
    debug: TelemetrySeverity.Verbose,
    audit: TelemetrySeverity.Critical, // custom level
  },
  traceFilter: (trace) => trace.severity !== KnownSeverityLevel.Verbose,
  exceptionFilter: (exception) => !exception.exception.message.includes('ECONNRESET'),
  isError: (obj) => obj instanceof Error,
});

// --- SDK v2 support ---
const v2Transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V2,
  client: applicationinsights.defaultClient,
});
```
```

--------------------------------

### Dual SDK Support (v2 and v3)

Source: https://github.com/shellicar/ecosystem/blob/main/packages/winston-azure-application-insights/README.md

Demonstrates compatibility with both Application Insights SDK versions v2 and v3. The `version` option in `createApplicationInsightsTransport` specifies which SDK to target.

```typescript
// Application Insights v2
import applicationinsights from 'applicationinsights'; // v2
const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V2,
  client: applicationinsights.defaultClient,
});

// Application Insights v3
import applicationinsights from 'applicationinsights'; // v3
const transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V3,
  client: applicationinsights.defaultClient,
});
```

--------------------------------

### Create Application Insights Transport for SDK v2

Source: https://context7.com/shellicar/ecosystem/llms.txt

Initializes a standalone Winston transport specifically for Application Insights SDK v2.

```typescript
const v2Transport = createApplicationInsightsTransport({
  version: ApplicationInsightsVersion.V2,
  client: applicationinsights.defaultClient,
});
```

--------------------------------

### Create Factory for Secure Configuration Values

Source: https://context7.com/shellicar/ecosystem/llms.txt

Use `createFactory` to wrap sensitive strings, connection strings, and URLs. These wrapped values are automatically SHA-256-hashed when serialized or logged, with the raw secret accessible via `.secretValue`. Supports custom secret key detection in connection strings and HMAC mode.

```typescript
import { createFactory } from '@shellicar/core-config';
import { z } from 'zod';
import { env } from 'node:process';

// --- SecureString ---
const factory = createFactory();
const secret = factory.string('myPassword123');
console.log(secret.toString());
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716
console.log(JSON.stringify({ secret }));
// {"secret":"sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716"}

// --- SecureConnectionString ---
const conn = factory.connectionString('Server=myserver;Password=myPassword123');
console.log(conn.toString());
// Server=myserver;Password=sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

// Custom secret key detection
const conn2 = factory.connectionString('Server=myserver;SuperSecretKey=myPassword123', ['SuperSecretKey']);
console.log(conn2.toString());
// Server=myserver;SuperSecretKey=sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

// --- SecureURL ---
const url = factory.url(new URL('https://user:myPassword123@example.com?key=value'));
console.log(url.toString());
// https://user:sha256%3A...@example.com/?key=value

// --- HMAC mode ---
const hmacFactory = createFactory({ secret: 'myHmacSecret' });
const hmacSecret = hmacFactory.string('myPassword123');
console.log(hmacSecret.toString()); // sha256:<hmac-hash>

// --- Integration with Zod for environment variable validation ---
const envSchema = z.object({
  MONGODB_URL: z.string().url().transform((x) => factory.url(new URL(x))),
  API_KEY: z.string().min(1).transform((x) => factory.string(x)),
  SQL_CONNECTION: z.string().transform((x) => factory.connectionString(x)),
});

const config = envSchema.parse(env);
// All values are SecureString/SecureURL instances — safe to log, compare, and inspect
console.log(config.API_KEY.toString()); // sha256:...
console.log(config.SQL_CONNECTION.toString()); // Server=...;Password=sha256:...

```