### Project Setup and Running Instructions

Source: https://github.com/skiplabs/skip/blob/main/www/blog/chat_with_react_vite.md

These commands guide you through setting up and running the Skip service with the React + Vite frontend. It involves navigating to the project directory, running a setup script, and then starting both the reactive service and the frontend development server.

```bash
cd my-skip-chat
./setup.sh

```

```bash
cd reactive_service && pnpm start

```

```bash
cd frontend && pnpm dev

```

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

### Build and Run Skip Example

Source: https://github.com/skiplabs/skip/blob/main/www/docs/getting_started.md

Commands to build and run the Skip example project. This includes navigating to the example directory, building the project, and running the server and main service scripts in the background.

```bash
cd skipruntime-ts/examples
npm run build
node dist/groups-server.js &
node dist/groups.js &
```

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

### Create and Run a Distributed Skip Service Example

Source: https://github.com/skiplabs/skip/blob/main/www/blog/scaling.md

This command sequence demonstrates how to create a new Skip service using a 'hackernews' example and then run it in a distributed configuration using Docker Compose. It requires Node.js and Docker to be installed.

```bash
npx create-skip-service hackernews --example hackernews --verbose
docker compose -f hackernews/compose.distributed.yml up --build
```

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

### Install Skip Dependencies

Source: https://github.com/skiplabs/skip/blob/main/www/blog/postgresql_and_skip_poc.md

Installs the necessary Skip runtime core, helpers, server packages, and the PostgreSQL adapter. This command ensures all required dependencies are available for the Skip service.

```bash
git checkout main
pnpm add -D @skipruntime/core @skipruntime/helpers @skipruntime/server
pnpm add @skip-adapter/postgres
```

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

### Start Skip Server

Source: https://github.com/skiplabs/skip/blob/main/www/blog/postgresql_and_skip_poc.md

Executes a shell script to initialize and start the Skip server. This is the first step in running the Skip service and making it available for connections.

```bash
./init_and_start_server.sh
```

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

### Install Skip NPM Package

Source: https://context7.com/skiplabs/skip/llms.txt

Installs the core Skip NPM package and its associated runtime and helper packages. This command is used to set up the Skip framework for a new project.

```bash
npm install @skiplabs/skip
```

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

### Install @skiplabs/skip Package

Source: https://github.com/skiplabs/skip/blob/main/www/blog/reactive_social_skip_service_poc.md

Installs the necessary SkipLabs packages for the project using npm. This is the first step to include Skip functionality in your project.

```bash
npm add @skiplabs/skip
```

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

### Install Skip Runtime Native Add-on (Bash)

Source: https://github.com/skiplabs/skip/blob/main/skipruntime-ts/addon/README.md

This bash script automates the installation of the Skip runtime native library and the @skipruntime/native npm package. It first determines the correct version using `npm install --dry-run` to respect package.json constraints, then downloads and installs the binary release, and finally installs the npm package. Ensure the versions of the binary and the npm package match to avoid installation errors.

```bash
# calculate the version of the skipruntime
  VERSION=$(npm install --dry-run @skipruntime/native | grep native | cut -d' ' -f3) \
# install the skipruntime binary release
&& wget --quiet --output-document=-\
      https://raw.githubusercontent.com/skiplabs/skip/refs/tags/v${VERSION}/bin/install_runtime.sh \
  | VERSION=${VERSION} bash - \
# install the skipruntime native node addon package
&& npm install @skipruntime/native
```

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

### Install Skip Framework using npm

Source: https://github.com/skiplabs/skip/blob/main/www/blog/skip_alpha.md

This command installs the Skip Framework package from npm. It is a prerequisite for using the Skip Framework in your project.

```bash
npm i @skiplabs/skip
```

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

### Apply Kubernetes Manifests and Install HAProxy Helm Chart (Bash)

Source: https://github.com/skiplabs/skip/blob/main/examples/hackernews/kubernetes/eks/guide.md

Applies Kubernetes manifests and installs the HAProxy Helm chart for the Skip service deployment. It uses `sed` to substitute the ECR repository URI into the manifests before applying them with `kubectl`, and then configures and installs the HAProxy ingress controller using Helm.

```bash
for f in kubernetes/eks/*.yaml ; do
	sed <$f s%__ECR__%$ECR% | kubectl apply -f - ;
done

kubectl create configmap haproxy-auxiliary-configmap \
    --from-file kubernetes/distributed_skip/haproxy-aux.cfg
helm repo add haproxytech https://haproxytech.github.io/helm-charts
helm repo update
helm install haproxy haproxytech/kubernetes-ingress \
	-f kubernetes/distributed_skip/haproxy-helm-config
```

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

### Install, Serve, Build, and Lint Dependencies (Bash)

Source: https://github.com/skiplabs/skip/blob/main/examples/cache_invalidation/www/README.md

Commands for managing project dependencies and running development or production builds. Uses pnpm for package management.

```bash
# Install dependencies
pnpm install

# Development server with hot reload
pnpm run serve

# Build for production
pnpm run build

# Lint and fix files
pnpm run lint
```

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

### Set Up TypeScript Project with npm and tsc

Source: https://github.com/skiplabs/skip/blob/main/www/blog/reactive_social_skip_service_poc.md

Initializes a Node.js project with TypeScript, installs necessary development dependencies, and configures TypeScript compilation settings. This sets up the foundational structure for the reactive application.

```bash
mkdir reactive_social_network_service
cd reactive_social_network_service
npm init -y
npm install --save-dev typescript @types/node
mkdir -p src
npx tsc --init \
    --target ES2022 \
    --module nodenext \
    --rootDir "./src" \
    --outDir "./dist" \
    --moduleResolution nodenext
```

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

### Client Schema Transformation Example (SQL)

Source: https://github.com/skiplabs/skip/blob/main/rfc/007-schema-migration.md

This example shows a server schema and a client schema. The server records a fieldTransform to map its columns to the client's schema, handling cases where the client schema is a subset or has a different column order.

```sql
-- Server Schema:
-- (id INTEGER PRIMARY KEY, x TEXT, y TEXT, skdb_access TEXT, addedCol TEXT)
-- Client Schema:
-- (x TEXT, y TEXT, skdb_access TEXT, id INTEGER PRIMARY KEY)
-- Server fieldTransform: [1, 2, 3, 0]
```

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

### Build and Run Skip Service with Dockerfile

Source: https://github.com/skiplabs/skip/blob/main/www/docs/deploying.md

This Dockerfile sets up an environment to build and run a Skip reactive service. It installs Node.js dependencies, copies project files, builds the service, and exposes the default streaming and control ports.

```Dockerfile
FROM node:lts-alpine3.19
WORKDIR /app
COPY package.json package.json
RUN npm install
COPY . .
RUN npm run build
EXPOSE 8080 8081
CMD ["npm", "start"]
```

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

### Listen for Updates with Curl

Source: https://github.com/skiplabs/skip/blob/main/www/docs/getting_started.md

Example of using curl to listen for real-time updates from a Skip service. This command connects to the active_friends resource for user ID 0 and streams the raw event data.

```bash
curl -LN http://localhost:8082/active_friends/0
```

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

### Configure package.json for TypeScript Project

Source: https://github.com/skiplabs/skip/blob/main/www/blog/reactive_social_skip_service_poc.md

Configures the 'package.json' file to set the project type to 'module', and defines scripts for building, starting, and cleaning the project. These scripts streamline the development workflow.

```bash
npm pkg set type="module"
npm pkg set scripts.build="tsc"
npm pkg set scripts.start="node dist/index.js"
npm pkg set scripts.clean="rm -rf dist node_modules"
```

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

### Initialize and Run Docusaurus API Docs Locally

Source: https://github.com/skiplabs/skip/blob/main/www/README.md

Commands to initialize the API documentation using Make, run the Docusaurus development server locally, and access the documentation site.

```bash
# Initialize the API docs
$ cd /path/to/repo/root
$ make docs

# Run the docs site locally
$ make docs-run

# Visit the docs site
# http://localhost:3000/docs/api/core
```

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

### Run a Skip Service with Reactive Computation (TypeScript)

Source: https://github.com/skiplabs/skip/blob/main/www/docs/getting_started.md

Demonstrates how to define and run a Skip service. It includes setting up initial data, defining input and resource types, and creating a computation graph using mappers to process user and group data reactively.

```typescript
import {
    type EagerCollection,
    type InitialData,
    type Mapper,
    type Values,
} from "@skipruntime/core";

// Type alias for inputs to our service
type ServiceInputs = {
  users: EagerCollection<UserID, User>;
  groups: EagerCollection<GroupID, Group>;
};

// Type alias for inputs to the active friends resource
type ResourceInputs = {
  users: EagerCollection<UserID, User>;
  activeMembers: EagerCollection<GroupID, UserID>;
};

// Mapper function to compute the active users of each group
class ActiveMembers implements Mapper<GroupID, Group, GroupID, UserID> {
  constructor(private users: EagerCollection<UserID, User>) {}

  mapEntry(gid: GroupID, group: Values<Group>): Iterable<[GroupID, UserID]> {
    return group
      .getUnique()
      .members.flatMap((uid) =>
        this.users.getUnique(uid).active ? [[gid, uid]] : [],
      );
  }
}

// Load initial data from a source-of-truth database (empty for now for simplicity)
const initialData: InitialData<ServiceInputs> = {
  users: [],
  groups: [],
};

// Specify and run the reactive service
const service = {
  initialData,
  resources: {},
  createGraph(input: ServiceInputs): ResourceInputs {
    const activeMembers = input.groups.map(ActiveMembers, input.users);
    return { users: input.users, activeMembers };
  },
};
await runService(service);
```

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

### HMAC-SHA256 Signature Calculation Example

Source: https://github.com/skiplabs/skip/blob/main/rfc/002-auth.org

Illustrates the process of generating a signature for authentication messages using HMAC-SHA256. This involves combining specific message components and signing them with a private key.

```text
signature = Base-64(
  HMAC-SHA-256(
    UTF8-Encoded(private-key),
    UTF8-Encoded(
      "auth" || access-key || iso8601-now || nonce
    )
  )
)
```

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

### Publish API Docs to Live Site

Source: https://github.com/skiplabs/skip/blob/main/www/README.md

Commands to publish the generated API documentation to the live website. This involves testing locally, committing changes, and pushing to the repository that feeds the live site.

```bash
# Publish the docs
$ make docs-publish

# Test locally (optional, but recommended)
# make docs-serve

# Push to live site
cd www/docs_site/; git add -A; git commit -m 'update to <commit>'; git push; cd -
```

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

### Read Entire Reactive Collection (GET)

Source: https://github.com/skiplabs/skip/blob/main/rfc/008-reactive-services.org

This code shows how to retrieve the entire content of a reactive collection at the current tick using an HTTP GET request. It includes optional authentication headers and demonstrates how query parameters are passed down to the resource.

```http
GET /{resource} HTTP/1.1
Host: your-reactive-service.com
Skip-Reactive-Auth: {your_auth_token}

// Query parameters can be appended here, e.g., ?filter=active
```

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

### Create Input Directory with SKStore

Source: https://github.com/skiplabs/skip/blob/main/skiplang/docs/SKStore.md

Demonstrates how to create an input directory in SKStore, specifying key and value types. Input directories can be modified externally. The keyType and type fields are inherited from SKStore.Key and SKStore.File respectively.

```SKStore
myInputDirectory = context.mkdir(Type1::keyType, Type2::type, "/myInput/Name/")
```

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

### Define Resource Instantiation for Skip Service (TypeScript)

Source: https://github.com/skiplabs/skip/blob/main/www/docs/getting_started.md

Illustrates how to define resources within a Skip service that can be dynamically instantiated based on incoming requests. This involves importing necessary types and setting up mappers to filter friends based on user activity and group membership.

```typescript
import {
    type EagerCollection,
    type InitialData,
    type Mapper,
    type Values,
    type Json,
    type Resource,
} from "@skipruntime/core";

// ... rest of your code so far

// Mapper function to find users that are active and also friends with `user`
class FilterFriends implements Mapper<GroupID, UserID, GroupID, UserID> {
  constructor(private readonly user: User) {}

  mapEntry(gid: GroupID, uids: Values<UserID>): Iterable<[GroupID, UserID]> {
    return uids
      .toArray()

```

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

### Example: Active Members Mapper

Source: https://github.com/skiplabs/skip/blob/main/www/docs/functions.md

An example implementation of the `Mapper` interface to compute active users within each group. This mapper takes a `GroupID` and `Group` values, and outputs `GroupID` to `UserID` pairs for active members. It demonstrates accessing external collections (`users`) within the `mapEntry` function.

```typescript
// Mapper function to compute the active users of each group
class ActiveMembers implements Mapper<GroupID, Group, GroupID, UserID> {
  constructor(private users: EagerCollection<UserID, User>) {}

  mapEntry(gid: GroupID, group: Values<Group>): Iterable<[GroupID, UserID]> {
    return group
      .getUnique()
      .members.flatMap((uid) =>
        this.users.getUnique(uid).active ? [[gid, uid]] : [],
      );
  }
}
```

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

### Run Skip Service and Broker

Source: https://github.com/skiplabs/skip/blob/main/www/docs/getting_started.md

This TypeScript code demonstrates how to define and run a Skip reactive service. It includes setting up the service definition with initial data and resources, creating a graph, and then running the service and broker on specified ports.

```typescript
import { runService } from "@skipruntime/server";

// Service definition
const service = {
    initialData,
    resources: { active_friends: ActiveFriends },
    createGraph(input: ServiceInputs): ResourceInputs {
        const users = input.users;
        const activeMembers = input.groups.map(ActiveMembers, users);
        const _groupsPerUser = input.groups.map(GroupsPerUser);
        const _numFriendsPerUser = users.map(NumFriendsPerUser);
        const _numActiveMembers = activeMembers.map(NumActiveMembers);
        return { users, activeMembers };
    },
};

// Run the reactive service
const server = await runService(service, {
    streaming_port: 8080,
    control_port: 8081,
});

// Initialize the SkipServiceBroker
const serviceBroker = new SkipServiceBroker({
    host: "localhost",
    control_port: 8081,
    streaming_port: 8080,
});
```

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

### Update Docker Compose Package Dependencies

Source: https://github.com/skiplabs/skip/blob/main/bin/README.md

This command uses 'grep' and 'sed' to update package dependencies within the Docker Compose examples. It replaces old version strings with new ones to ensure the examples use the latest released NPM packages.

```bash
sed -i '' 's/$OLD/$NEW/g' $(g grep -l $OLD examples/**/package.json)
```

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

### Run Skip Reactive Service with runService

Source: https://context7.com/skiplabs/skip/llms.txt

Initializes and starts a reactive Skip service using the `runService` function. This function takes a SkipService specification, including initial data, resources, and the computation graph, and starts HTTP and streaming APIs. It supports different runtime platforms like 'wasm' or 'native'.

```typescript
import {
  type EagerCollection,
  type InitialData,
  type Mapper,
  type Resource,
  type Values,
  type Json,
} from "@skipruntime/core";
import { runService } from "@skipruntime/server";

// Define types for the service
type UserID = number;
type User = { name: string; active?: boolean; friends: UserID[] };

type ServiceInputs = {
  users: EagerCollection<UserID, User>;
};

type ResourceInputs = {
  users: EagerCollection<UserID, User>;
  activeUsers: EagerCollection<UserID, User>;
};

// Mapper to filter active users
class ActiveUsers implements Mapper<UserID, User, UserID, User> {
  mapEntry(uid: UserID, users: Values<User>): Iterable<[UserID, User]> {
    const user = users.getUnique();
    return user.active ? [[uid, user]] : [];
  }
}

// Resource to expose active users
class ActiveUsersResource implements Resource<ResourceInputs> {
  constructor(_params: Json) {}

  instantiate(inputs: ResourceInputs): EagerCollection<UserID, User> {
    return inputs.activeUsers;
  }
}

// Initial data
const initialData: InitialData<ServiceInputs> = {
  users: [
    [1, [{ name: "Alice", active: true, friends: [2, 3] }]],
    [2, [{ name: "Bob", active: false, friends: [1] }]],
    [3, [{ name: "Carol", active: true, friends: [1, 2] }]],
  ],
};

// Define and run the service
const service = {
  initialData,
  resources: { active_users: ActiveUsersResource },
  createGraph(input: ServiceInputs): ResourceInputs {
    const activeUsers = input.users.map(ActiveUsers);
    return { users: input.users, activeUsers };
  },
};

const server = await runService(service, {
  streaming_port: 8080,
  control_port: 8081,
  platform: "wasm", // or "native"
});

// Graceful shutdown
process.on("SIGTERM", async () => {
  await server.close();
});

```

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

### Build and Push Docker Images for Skip Service (Bash)

Source: https://github.com/skiplabs/skip/blob/main/examples/hackernews/kubernetes/eks/guide.md

Builds and pushes Docker images for various components of the Reactive HackerNews example service to an ECR repository. It iterates through a list of services, builds their Docker images, tags them with the ECR repository URI, and pushes them.

```bash
for image in web_service reactive_service www db reverse_proxy ; do
  docker build --platform linux/amd64 --tag rhn-$image-aws $image
  docker tag rhn-$image-aws $ECR:$image;
  docker push $ECR:$image;
done
```

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

### Create Eager Directory using Map in SKStore

Source: https://github.com/skiplabs/skip/blob/main/skiplang/docs/SKStore.md

Illustrates the creation of an eager directory by mapping over an existing directory. The map operation computes a result for each entry and stores it in a new directory. Changes in the source directory automatically update the eager directory.

```SKStore
sumDir = myDirOfIntegers.map(
  IID::keyType,
  IntFile::type,
  context,
  "/result/",
  (context, writer, key, fileIterator) ~> {
    sum = 0;
    for(intFile in fileIterator) {
      sum = sum + intFile.value
    };
    writer.set(key, IntFile(sum));
  }
)
```

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

### HEAD Request for Resource

Source: https://github.com/skiplabs/skip/blob/main/rfc/008-reactive-services.org

Similar to GET /{resource}, but returns no data in the body. Useful for obtaining a replication token when using the Skip-Reactive-Auth header.

```APIDOC
## HEAD /{resource}

### Description
Identical to `GET /{resource}`, except that no data is returned in the response body. This is primarily useful when setting the `Skip-Reactive-Auth` header to obtain a replication token for initial data handling via the replication client.

### Method
HEAD

### Endpoint
`/{resource}`

### Parameters
#### Path Parameters
- **resource** (string) - Required - The name of the reactive resource.

#### Query Parameters
- **(any)** - Optional - Query parameters are passed down to the reactive resource.

#### Request Body
None

### Request Example
```http
HEAD /my_collection HTTP/1.1
Host: reactive.example.com
Skip-Reactive-Auth: <your_auth_token>
```

### Response
#### Success Response (200)
No response body is returned.
- **X-Reactive-Response-Token** (string) - Optional - A token to be used for WebSocket streaming if `Skip-Reactive-Auth` was provided.

#### Headers Example (if Skip-Reactive-Auth is used)
```http
X-Reactive-Response-Token: abcdef123456
```
```

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

### Initialize a New Skip Service with CLI

Source: https://github.com/skiplabs/skip/blob/main/www/blog/create_skip_service_announcement.md

This command initializes a new Skip service project. You can specify the project name and various options to customize the setup, such as selecting a template, disabling Git initialization, or enabling verbose logging.

```bash
npx create-skip-service <project-name> <options>
```

```bash
npx create-skip-service my-service
```

```bash
npx create-skip-service my-service --template with_postgres
```

```bash
npx create-skip-service my-service --nogit
```

```bash
npx create-skip-service my-service --verbose
```

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

### Synchronous Resource Read (GET /v1/snapshot)

Source: https://github.com/skiplabs/skip/blob/main/www/docs/client.md

Allows for synchronous reads of resource data at a specific key. This requires instantiation of the resource.

```APIDOC
## GET /v1/snapshot

### Description
Synchronously reads data from a resource instance at a specific key. This operation requires the resource to be instantiated.

### Method
GET

### Endpoint
`/v1/snapshot`

### Parameters
#### Query Parameters
- **resource_name** (string) - Required - The name of the resource to read.
- **key** (string) - Required - The specific key within the resource to retrieve data for.
- **params** (object) - Optional - Additional parameters for resource instantiation and filtering.

### Request Example
```
GET /v1/snapshot?resource_name=my_resource&key=foo/key1&params.id=123
```

### Response
#### Success Response (200)
- **data** (any) - The data associated with the specified resource and key.

#### Response Example
```json
{
  "data": [
    "value1",
    "value2"
  ]
}
```
```

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

### Health Check (Control API)

Source: https://github.com/skiplabs/skip/blob/main/www/docs/resources.md

Checks the operational status of the service. GET /healthz returns an HTTP 200 status code if the service is healthy.

```http
GET /healthz
```

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

### Control API - Read/Write Data with Bash

Source: https://context7.com/skiplabs/skip/llms.txt

Provides HTTP endpoints for synchronous reads of resources and writes to input collections served on the `control_port`. Examples include reading entire resources, specific keys, updating input collections, deleting entries, creating/deleting streams for subscriptions, and health checks.

```bash
# Read entire resource (POST /v1/snapshot/:resource)
curl -X POST http://localhost:8081/v1/snapshot/active_users \
  -H "Content-Type: application/json" \
  -d '{}'
# Response: [[1, [{"name": "Alice", "active": true}]], [3, [{"name": "Carol", "active": true}]]]

# Read specific key (POST /v1/snapshot/:resource/lookup)
curl -X POST http://localhost:8081/v1/snapshot/active_users/lookup \
  -H "Content-Type: application/json" \
  -d '{"key": 1, "params": {}}'
# Response: [{"name": "Alice", "active": true}]

# Update input collection (PATCH /v1/inputs/:collection)
curl -X PATCH http://localhost:8081/v1/inputs/users \
  -H "Content-Type: application/json" \
  -d '[[2, [{"name": "Bob", "active": true, "friends": [1]}]]]'

# Delete entry (set values to empty array)
curl -X PATCH http://localhost:8081/v1/inputs/users \
  -H "Content-Type: application/json" \
  -d '[[2, []]]'

# Create stream UUID for subscription
curl -X POST http://localhost:8081/v1/streams/active_users \
  -H "Content-Type: application/json" \
  -d '{}'
# Response: "550e8400-e29b-41d4-a716-446655440000"

# Delete stream
curl -X DELETE http://localhost:8081/v1/streams/550e8400-e29b-41d4-a716-446655440000

# Health check
curl http://localhost:8081/healthz
# Response: HTTP 200

```

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

### Read Single Key from Reactive Collection

Source: https://github.com/skiplabs/skip/blob/main/rfc/008-reactive-services.org

This code demonstrates how to fetch a specific key's value from a reactive collection using an HTTP GET request with a key in the path. Query parameters are also supported.

```http
GET /{resource}/{key} HTTP/1.1
Host: your-reactive-service.com
```