@greener-games/vue3-sharepoint-plugin

@greener-games/vue3-sharepoint-plugin

A robust, type-safe wrapper for SharePoint operations in Vue 3 applications. This plugin provides a unified interface for Search, CRUD, File operations, and Batching, supporting both PnPjs (Production) and an in-memory Mock Engine (Development/Testing).

Features

• 🔍 Unified Search Engine: Isolated search instances, fluent query execution, token replacement, and metadata adapters.
• ⚡ Multiple Clients: Support for PnPjs, raw SharePoint REST API, and an in-memory Mock Engine.
• 🧪 Offline Mocking: Built-in mock data generators for users, groups, and documents to develop and test without a live SharePoint connection.
• 📁 File & Folder Operations: Unified methods for querying, uploading, downloading, and moving documents.
• 📦 Batch Operations: Group multiple requests together to minimize round-trips.
• 🛡️ Type Safety: Strictly typed interfaces and composables for seamless Vue 3 Composition API usage.

📦 Installation

npm install @greener-games/vue3-sharepoint-plugin
# or
yarn add @greener-games/vue3-sharepoint-plugin
# or
pnpm add @greener-games/vue3-sharepoint-plugin

Note: For production use with PnPSharePointClient, PnPjs dependencies (@pnp/sp, @pnp/logging, @pnp/queryable) are bundled automatically.

Local Development / Monorepo Linking

If developing or testing locally within a monorepo workspace:

npm install ./plugins/@greener-games/vue3-sharepoint-plugin

⚙️ Configuration (main.ts)

Register the plugin in your main entry file (main.ts). You can switch between Real and Mock clients based on the environment.

Option A: Quick Mock Setup (Recommended)

Use the built-in createMockData factory to instantly generate users, groups, and hundreds of dummy documents with rich metadata.

import { createApp } from 'vue'
import App from './App.vue'
import {
  SharePointPlugin,
  PnPSharePointClient,
  MockSharePointClient,
  createMockData
} from '@greener-games/vue3-sharepoint-plugin'

const app = createApp(App)
const isDev = import.meta.env.DEV

let client

if (isDev) {
  // --- DEVELOPMENT: Use Generated Mock Data ---
  // Generates 100 documents located at the specified site URL
  const mockData = createMockData(100, '/sites/Intranet')

  console.log('🚧 Running with Mock Data', mockData)
  client = new MockSharePointClient(mockData)
} else {
  // --- PRODUCTION: Use Real PnPjs ---
  client = new PnPSharePointClient({
    baseUrl: 'https://your-tenant.sharepoint.com/sites/Intranet',
    enableCache: true, // Caches User Info & List Fields in SessionStorage
  })
}

app.use(SharePointPlugin, { client })
app.mount('#app')

Option B: Custom Mock Setup (Advanced)

If you need specific testing scenarios, you can define the MockData object manually or use the exposed helper functions.

import {
  MockSharePointClient,
  createMockUser,
  type MockData
} from '@greener-games/vue3-sharepoint-plugin'

const customMock: MockData = {
  currentUser: createMockUser(1, 'Tester', 'test@local'),
  // Define specific lists
  lists: {
    '/sites/dev/Lists/Projects': [
      { Id: 1, Title: 'Project Alpha', Status: 'Active' },
      { Id: 2, Title: 'Project Beta', Status: 'Closed' }
    ]
  },
  delay: 1000 // Simulate slow network (1s latency)
}

const client = new MockSharePointClient(customMock)

📘 Mock Factory API Reference

These utilities help generate data for the MockSharePointClient.

createMockData(docCount, baseUrl)

createMockUser(id, name, email)

🔍 Search Engine

The search engine uses a Factory Pattern. You create an isolated search instance for every search interface.

Usage Example

<script setup lang="ts">
import { useSharePoint } from '@greener-games/vue3-sharepoint-plugin'

// 1. Get the factory
const { createSearch } = useSharePoint()

// 2. Create an isolated instance
const searchCtx = createSearch()

const handleSearch = () => {
  searchCtx.execute({
    query: 'Engineering',
    rowLimit: 10,
    scope: 'Shared Documents', // Automatically inferred as relative to baseUrl
    resultType: 'items', // Exclude folders
    includeRelativePath: true, // Returns a 'relativePath' field
    fileTypes: {
      include: ['docx', 'pdf'],
      exclude: ['aspx']
    },
    filters: {
      'RefinableString01': ['UK', 'US'], // Array = OR Logic
    },
    mapping: {
      'Title': 'title',
      'Path': 'url',
      'RefinableString01': 'region'
    }
  })
}
</script>

📘 Search API Reference

searchCtx.execute(options) Performs a search query. This updates searchCtx.results.

🚀 Advanced Search & Hydration

You can perform Hydration (fetching the actual list item for each search result) to access expanded fields like User details or Lookup values.

1. Standard Search

Just gets properties from the Search Index. Fast and simple.

const results = await searchCtx.execute({
  query: 'ContentType:Document',
  selectFields: ['Title', 'Path', 'Author', 'Created'],

  mapping: {
    'Path': 'url',
    'Created': 'date'
  }
})

2. Advanced Search (Hydration) with Deep Mapping

Fetches the underlying List Item to get data not in the search index (e.g., expanded User objects).

How it works:

• Add expandFields to trigger hydration.
• Put ALL desired fields in selectFields. The plugin automatically routes them:
  • Search Index: Gets standard properties + anything looking like a Managed Property.
  • List Item: Gets columns + expanded fields (anything with /).

const results = await searchCtx.execute({
  query: 'ContentType:Document',

  // 1. List EVERYTHING you want
  selectFields: [
    'Title', 'Path', 'HitHighlightedSummary', // Search Props
    'Author/Title', 'Author/Email',           // List Expansions (auto-routed to List)
    'Department/Title'
  ],

  // 2. Trigger Hydration
  expandFields: ['Author', 'Department'],

  // 3. Deep Mapping
  mapping: {
    'Path': 'document.url',           // Map standard prop
    'Author.Title': 'meta.owner',     // Map hydrated prop to nested object
    'Department.Title': 'meta.dept'
  }
})

/* Result Structure:
{
  Title: "...",
  HitHighlightedSummary: "<b>...</b>",
  document: { url: "..." },
  meta: {
    owner: "John Doe",
    dept: "IT"
  }
}
*/

📝 Lists & Items (CRUD)

All CRUD methods are available directly from useSharePoint().

Usage Example

import { useSharePoint } from '@greener-games/vue3-sharepoint-plugin'

const { addItem, updateItem, deleteItem } = useSharePoint()

const newItem = await addItem('Tasks', { Title: 'New Task' })
await updateItem('Tasks', newItem.Id, { Status: 'Active' })

📘 List API Reference

addItem(listTitle, payload)

updateItem(listTitle, id, payload)

deleteItem(listTitle, id)

getItem(listTitle, id, select?, expand?)

getItems(listTitle, options?)

📂 Files & Folders

Helper methods for Document Libraries.

Usage Example

const { upload, downloadAndSave, createFolder } = useSharePoint()

await createFolder('/sites/Dev/Docs/NewFolder')
await upload('/sites/Dev/Docs', 'report.pdf', fileBlob)

📘 Files API Reference

Paths can be either:

• Site-Relative: 'Shared Documents' (automatically prepends baseUrl)
• Server-Relative: '/sites/Intranet/Shared Documents'

upload(serverRelativeUrl, fileName, file)

createFolder(serverRelativeUrl)

updateFileMetadata(serverRelativeUrl, payload)

getVersions(serverRelativeUrl)

downloadAndSave(serverRelativeUrl, fileName)

🔐 Permissions & Users

Utilities for checking permissions and retrieving user info.

Usage Example

const { getPermissions, hasPermission, PermissionKind } = useSharePoint()

const perms = await getPermissions()
if (hasPermission(perms, PermissionKind.ManageWeb)) {
  console.log('User is Admin')
}

📘 Permissions API Reference

getSiteUsers() Returns all users from the User Information List of the site.

• Returns: Promise<UserInfo[]>

getUserGroups(email?)

getPermissions(email?)

hasPermission(permissions, kind)

🚀 Batching

Execute multiple write operations in a single HTTP request.

Usage Example

const { executeBatch } = useSharePoint()

await executeBatch((batch) => {
  batch.createListItem('Tasks', { Title: 'A' })
  batch.deleteFile('/sites/dev/docs/old.pdf')
})

📘 Batch API Reference

executeBatch(callback)

Methods available on batch object:

🛠 Utilities

📘 Utilities API Reference

loadUser() Returns the current logged-in user. Caches the result to avoid repeated API calls.

• Returns: Promise<UserInfo> { Id, Title, Email, LoginName }

getFields(listTitle)

getChoices(listTitle, fieldName)

License

MIT